# Untitled UI auth.md

How AI agents, MCP clients and tools get credentials for Untitled UI.

- Service: https://www.untitledui.com
- API catalog: https://www.untitledui.com/.well-known/api-catalog
- OpenAPI description: https://www.untitledui.com/react/openapi.json

## Who needs credentials

Free components, icons, search and the public registry need no credentials. Credentials are only needed to reach **PRO** components and page templates, and they belong to a person who holds an Untitled UI React license (bought directly or through a team seat). An agent always acts on behalf of that person. There is no agent-only or anonymous account.

## Protected resource

| Resource | URL |
| --- | --- |
| MCP server (Streamable HTTP) | `https://www.untitledui.com/react/api/mcp` |
| MCP tool endpoints (HTTP) | `https://www.untitledui.com/react/api/mcp/tools/{tool}` |

Protected Resource Metadata (RFC 9728): https://www.untitledui.com/.well-known/oauth-protected-resource

An unauthenticated or invalid request for PRO content returns `401` with a `WWW-Authenticate: Bearer ... resource_metadata="..."` challenge pointing at that document.

## Method 1: OAuth 2.1 (recommended for MCP clients)

The MCP server accepts access tokens from the Untitled UI authorization server (hosted on Supabase Auth).

| | |
| --- | --- |
| Issuer | `https://wudwkfadpazwjkekvhzt.supabase.co/auth/v1` |
| Metadata (RFC 8414) | https://www.untitledui.com/.well-known/oauth-authorization-server |
| Dynamic client registration (RFC 7591) | `POST https://wudwkfadpazwjkekvhzt.supabase.co/auth/v1/oauth/clients/register` |
| Authorization endpoint | `https://wudwkfadpazwjkekvhzt.supabase.co/auth/v1/oauth/authorize` |
| Token endpoint | `https://wudwkfadpazwjkekvhzt.supabase.co/auth/v1/oauth/token` |
| Grant types | `authorization_code` (PKCE, `S256`), `refresh_token` |
| Scopes | `openid`, `email`, `profile` |

Flow:

1. Register a client with dynamic client registration (or reuse one you registered before).
2. Send the user to the authorization endpoint with a PKCE `S256` challenge. They sign in with a magic link and approve the client.
3. Exchange the code at the token endpoint.
4. Call the MCP server with `Authorization: Bearer <access_token>`. Refresh with the `refresh_token` grant when it expires.

MCP clients that support OAuth (Claude Code, Cursor, VS Code and others) run this flow automatically the first time a PRO tool is called.

## Method 2: API key (clients without OAuth, CLI, CI)

A license holder creates an API key at https://www.untitledui.com/account/api-keys. Keys are provisioned by the person in their account, not by an agent-callable endpoint.

Use the key the same way as an access token:

```http
Authorization: Bearer <api_key>
```

```bash
claude mcp add --transport http untitledui https://www.untitledui.com/react/api/mcp --header "Authorization: Bearer <api_key>"
```

The CLI stores a key for you after a browser sign-in (`npx untitledui@latest login`), or takes one per run with `--license <api_key>`.

## Using credentials

- Send credentials only in the `Authorization` header. Tokens in the query string or request body are ignored.
- Treat API keys as secrets: never commit them or echo them into logs, prompts or generated code.
- A key or token only grants access while the user's license (or team seat) is active.

## Documentation

- MCP setup: https://www.untitledui.com/react/integrations/mcp
- CLI: https://www.untitledui.com/react/docs/cli
