# Authentication for agents using Lottie Creator

This document walks through how an agent obtains access to Lottie Creator and the
LottieFiles MCP surfaces. It follows the section layout of the WorkOS auth.md convention
(https://github.com/workos/auth.md). Lottie Creator does not implement the `agent_auth`
extension: there is no `identity_endpoint`, no `identity_assertion` or ID-JAG exchange,
and no `service_auth` claim ceremony. Use the standard OAuth 2.1 flow described below, or
one of the two credential-free surfaces.

## Discover

There are three surfaces, each with a different credential story:

| Surface                  | Endpoint                                                         | Credentials                                                           |
| ------------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- |
| Creator MCP (local)      | stdio server from `npx -y @lottiefiles/creator-mcp@latest`       | None. It talks to the Creator tab already open in the user's browser. |
| WebMCP (in page)         | `document.modelContext` tools on https://creator.lottiefiles.com | None. Tools run inside the page with the user's own session.          |
| LottieFiles MCP (remote) | `https://mcp.lottiefiles.com/mcp` (Streamable HTTP)              | OAuth 2.1 bearer token, scope `mcp:full`.                             |

For the remote server, discovery is standards-based:

- An unauthenticated request to `https://mcp.lottiefiles.com/mcp` returns `401` with
  `WWW-Authenticate: Bearer resource_metadata="https://mcp.lottiefiles.com/.well-known/oauth-protected-resource/mcp", scope="mcp:full"`.
- Protected resource metadata (RFC 9728):
  https://mcp.lottiefiles.com/.well-known/oauth-protected-resource — lists
  `authorization_servers: ["https://mcp.lottiefiles.com"]`,
  `scopes_supported: ["mcp:full"]`, and `bearer_methods_supported: ["header"]`.
- Authorization server metadata (RFC 8414):
  https://mcp.lottiefiles.com/.well-known/oauth-authorization-server —
  `authorization_endpoint` `/authorize`, `token_endpoint` `/token`,
  `registration_endpoint` `/register`, `revocation_endpoint` `/revoke`,
  `code_challenge_methods_supported: ["S256"]`,
  `grant_types_supported: ["authorization_code", "refresh_token"]`,
  `token_endpoint_auth_methods_supported: ["none"]`, and
  `client_id_metadata_document_supported: true`.

## Pick a method

- Editing an animation on the user's screen: use Creator MCP or WebMCP. No registration,
  no token.
- Searching, fetching, or managing animations in a LottieFiles account: use the remote
  LottieFiles MCP with OAuth 2.1 authorization code + PKCE (S256).

## Register

Remote MCP only. Two options:

1. Client ID Metadata Documents (preferred): host a client metadata document at an HTTPS
   URL and use that URL as the `client_id`; the server advertises
   `client_id_metadata_document_supported`.
2. Dynamic Client Registration (RFC 7591): `POST https://mcp.lottiefiles.com/register`
   with your client metadata (`redirect_uris`, `client_name`, `grant_types`,
   `token_endpoint_auth_method: "none"`).

Creator MCP and WebMCP need no registration.

## Claim

There is no claim ceremony. The human user authorizes the agent interactively in the
browser during the authorization code flow, signing in with their LottieFiles account.
Agents must not ask users for LottieFiles passwords.

## Exchange

1. Open `https://mcp.lottiefiles.com/authorize` with `response_type=code`, your
   `client_id`, `redirect_uri`, `scope=mcp:full`, `state`, `code_challenge`, and
   `code_challenge_method=S256`.
2. The user signs in and consents; the server redirects back with `code`.
3. `POST https://mcp.lottiefiles.com/token` with `grant_type=authorization_code`, the
   `code`, `redirect_uri`, `client_id`, and `code_verifier`. The response includes
   `access_token` and `refresh_token`.
4. Refresh with `grant_type=refresh_token` when the access token expires.

## Use the access_token

Send `Authorization: Bearer <access_token>` on every request to
`https://mcp.lottiefiles.com/mcp`. Then initialize an MCP session as usual over Streamable
HTTP. Connection guide: https://docs.lottiefiles.com/en/platform/mcp/connect.md

## Errors

- `401` with `error="invalid_token"`: the token is missing, expired, or revoked. Re-read
  the `WWW-Authenticate` challenge and restart from Exchange (refresh first if you hold a
  refresh token).
- Creator MCP: if the local server cannot reach a Creator tab, ask the user to open
  https://creator.lottiefiles.com in their browser; the editor shows a Local MCP indicator
  in its header when connected.
- WebMCP: if `document.modelContext` is absent, the browser does not support WebMCP or the
  user disabled it under Settings → MCP Settings.

## Revocation

- `POST https://mcp.lottiefiles.com/revoke` with the token to revoke it (RFC 7009).
- Revoked tokens yield `401 invalid_token` on the next call; discard them and
  re-authorize.

## Related

- Hosted MCP documentation: https://docs.lottiefiles.com/en/platform/mcp.md
- Security at LottieFiles: https://lottiefiles.com/security
- Agent guide: https://creator.lottiefiles.com/agents.md