# auth.md

Layers is a search, merchandising and product discovery platform for Shopify
stores. This document tells an agent how to register, authenticate and call the
Layers agent surface.

https://www.uselayers.com is the marketing site. It has no protected API and
needs no credentials. Everything an agent can call lives on the Layers
application at https://app.uselayers.com, and the discovery documents on this
host mirror the application's metadata so that agents which start from the
marketing domain can find it.

## Audience

- Audience (resource): https://app.uselayers.com/mcp/v1
- Authorization server (issuer): https://app.uselayers.com
- Required scope: mcp:use
- Credential type: OAuth 2.1 bearer access token, sent in the
  `Authorization: Bearer <token>` header
- Documentation: https://docs.uselayers.com/developers/mcp-servers

## Endpoints

| Purpose                                 | URL                                                              |
| --------------------------------------- | ---------------------------------------------------------------- |
| Protected resource metadata             | https://app.uselayers.com/.well-known/oauth-protected-resource   |
| Authorization server metadata           | https://app.uselayers.com/.well-known/oauth-authorization-server |
| Client registration (RFC 7591)          | https://app.uselayers.com/oauth/register                         |
| Authorization                           | https://app.uselayers.com/oauth/authorize                        |
| Token                                   | https://app.uselayers.com/oauth/token                            |
| Layers MCP server (Streamable HTTP)     | https://app.uselayers.com/mcp/v1                                 |
| Storefront MCP server (Streamable HTTP) | https://app.uselayers.com/mcp/storefront/v1                      |

Mirrors of the two metadata documents are also served from this host at the same
paths.

## Supported methods

Layers supports one agent registration method: OAuth 2.1 dynamic client
registration (RFC 7591) followed by the authorization code flow with PKCE
(S256). There is no agent self-service credential endpoint, no ID-JAG assertion
support and no anonymous access. A human with Layers access must approve every
connection.

## Registration

Register a client at https://app.uselayers.com/oauth/register. Registration is
open, needs no initial access token, and returns a `client_id`. Public clients
are supported, so no client secret is required when you use PKCE.

```http
POST /oauth/register HTTP/1.1
Host: app.uselayers.com
Content-Type: application/json

{
  "client_name": "Your agent",
  "redirect_uris": ["https://your-agent.example/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "mcp:use"
}
```

## Authorization and tokens

1. `GET https://app.uselayers.com/.well-known/oauth-protected-resource` and read
   `authorization_servers`.
2. `GET https://app.uselayers.com/.well-known/oauth-authorization-server` and
   read `registration_endpoint`, `authorization_endpoint` and `token_endpoint`.
3. Register as above to get a `client_id`.
4. Send the user to https://app.uselayers.com/oauth/authorize with
   `response_type=code`, your `client_id`, `redirect_uri`, `scope=mcp:use`,
   `state`, `code_challenge` and `code_challenge_method=S256`.
5. The user signs in to the Layers dashboard and chooses which stores the
   connection may access and which of their own permissions it may use.
6. Exchange the returned code at https://app.uselayers.com/oauth/token with
   `grant_type=authorization_code`, your `client_id`, `redirect_uri`, `code` and
   `code_verifier`. Use `grant_type=refresh_token` with the returned refresh
   token to get a new access token.
7. Call the MCP endpoint with `Authorization: Bearer <access_token>`. A missing
   or expired token returns `401` with a `WWW-Authenticate` challenge pointing
   back at the protected resource metadata.

```http
POST /mcp/v1 HTTP/1.1
Host: app.uselayers.com
Authorization: Bearer <access_token>
Content-Type: application/json
```

## Credential use and revocation

- Access tokens are bearer tokens. Send them only in the `Authorization`
  header, over TLS, and never in a query string.
- A connection can never exceed the access of the person who approved it. If
  their access is reduced, the connection is reduced at the same time.
- Connections are store scoped. Tools called for a store that was not granted
  return a permission error.
- A merchant can review or revoke a connection in the Layers dashboard under
  access settings, on the app connections screen.
- Access tokens are RS256 JWTs. The signing public key is published at
  https://app.uselayers.com/oauth/jwks. A valid signature only proves the token
  was issued by Layers, not that it is still active. There is no introspection
  or revocation endpoint, so treat the token as opaque and read validity from
  API responses.

## Storefront access

The storefront MCP server and the Storefront REST API at
https://app.uselayers.com/api/storefront/v1 use a storefront access token
instead of OAuth. Merchants create those tokens in the dashboard. They are read
only and scoped to a single store.

## Notes for scanners

Do not send requests that could create accounts or credentials. Every document
listed above is a public `GET` and is the safe source of truth.