# Stunt Double auth.md

How an AI agent authenticates with Stunt Double. Stunt Double sends AI users (actors) through real products and returns evidence-backed results: checklist runs, user interviews and feedback. The Stunt Double Index ranks how agents experience the world's websites.

## Who this is for

Agents and MCP clients acting for a person who has, or will create, a Stunt Double account. There is no agent-only account and no anonymous access to a workspace: every credential is an access token that a person approved for their own account.

## What needs a credential

| Surface | Endpoint | Auth |
| --- | --- | --- |
| Product MCP server (workspaces, actors, checklists, interviews, runs, Index reports) | `https://app.stuntdouble.io/api/mcp` | OAuth 2.1 bearer token |
| Public docs MCP server | `https://www.stuntdouble.io/api/docs-mcp` | None |
| Stunt Double Index pages and `llms.txt` | https://index.stuntdouble.io | None |
| Everything else on https://www.stuntdouble.io (llms.txt, OpenAPI, manifests) | | None |

## Discovery

- Protected resource metadata (RFC 9728): `https://app.stuntdouble.io/.well-known/oauth-protected-resource`
- Authorization server metadata (RFC 8414): `https://app.stuntdouble.io/.well-known/oauth-authorization-server`. The issuer is `https://app.stuntdouble.io`.
- The authorization server metadata carries an `agent_auth` block. Its one identity type is `user_authorization`: `register_uri` is dynamic client registration and the credential is an access token from the authorization code flow below. ID-JAG, verified email and anonymous registration are not supported.
- An unauthenticated request to the MCP server answers `401` with a `WWW-Authenticate: Bearer` header whose `resource_metadata` points at the protected resource metadata, so a standard MCP client can start from the endpoint alone.

## Register a client

Dynamic client registration (RFC 7591), no pre-shared secret:

```http
POST https://app.stuntdouble.io/oauth/register
Content-Type: application/json

{
  "client_name": "Your agent",
  "redirect_uris": ["http://127.0.0.1:33418/callback"],
  "token_endpoint_auth_method": "none"
}
```

The response is `201` with your `client_id`. Clients are public: there is no client secret, and PKCE is required instead.

## Get a token

Authorization code flow with PKCE (`S256` only):

1. Send the person to `https://app.stuntdouble.io/oauth/authorize` with `response_type=code`, your `client_id`, `redirect_uri`, `code_challenge`, `code_challenge_method=S256`, `state` and the `scope` you need.
2. They sign in (a six-digit email code or Google) and approve the scopes on a consent screen.
3. Exchange the returned `code` and your `code_verifier` at `https://app.stuntdouble.io/oauth/token` with `grant_type=authorization_code`.

The person must be present for step 2. There is no client-credentials, device or token-exchange grant.

## Scopes

Request only what the task needs. A client that requests no scope is granted all three.

- `mcp:read`: Read workspaces and their contents: members, projects, actors, checklists, interviews, workflows, feedback, run results and Stunt Double Index reports.
- `mcp:write`: Create and edit projects, actors, actor knowledge, guidelines, checklists, interviews, workflows and feedback statuses.
- `mcp:run`: Start checklist runs, workflow runs, interviews and Stunt Double Index re-runs for domains you own. Checklist, workflow and interview runs consume the workspace run allowance.

Every tool also checks the person's membership of the workspace it is asked about, so a token never reaches further than its owner could in the dashboard.

## Use the credential

Send the access token in the `Authorization` header on every request to the MCP server:

```http
Authorization: Bearer <access_token>
```

Tokens are not accepted in query strings or form bodies. When a token expires the server answers `401` again: run the authorization flow again to get a new one.

## Without a credential

Agents that have not signed in can still learn what Stunt Double is and how to call it: read [llms.txt](https://www.stuntdouble.io/llms.txt), or connect to the public docs MCP server at `https://www.stuntdouble.io/api/docs-mcp`.

## Support

support@stuntdouble.io