# Orshot Agent Authentication (auth.md)

Orshot generates images, PDFs, and videos from templates via API. This file
tells agents how to register and authenticate to act on behalf of a user.

## Discover

1. Fetch the Protected Resource Metadata (RFC 9728):
   https://orshot.com/.well-known/oauth-protected-resource
2. Fetch the Authorization Server Metadata (RFC 8414):
   https://orshot.com/.well-known/oauth-authorization-server

Treat the metadata endpoints as authoritative if anything in this file
conflicts with them.

## Pick a method

- **OAuth (recommended for agents):** register a client dynamically, then get
  user consent via authorization code + PKCE, or the device code flow when you
  can't open a browser.
- **API key:** if the user already has an Orshot account, they can copy a
  workspace API key from their dashboard and give it to you directly. No
  registration needed. Guide:
  https://orshot.com/docs/quick-start/get-api-key

## Register (OAuth Dynamic Client Registration, RFC 7591)

```http
POST /v1/oauth/register HTTP/1.1
Host: api.orshot.com
Content-Type: application/json
```

```json
{
  "client_name": "Your Agent Name",
  "redirect_uris": ["https://your-agent.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none"
}
```

The response includes a `client_id`. Clients are public (PKCE required, no
client secret).

## Get user consent

**Authorization code + PKCE:** send the user to
`https://orshot.com/oauth/authorize` with `client_id`, `redirect_uri`,
`response_type=code`, `code_challenge` (S256), and `scope`. Exchange the
code at `https://api.orshot.com/v1/oauth/token`.

**Device code flow:** POST to
`https://api.orshot.com/v1/oauth/device/code`, show the user the
verification URL and code, then poll the token endpoint.

### Scopes

- `workspace:read`: List and read workspace details
- `workspace:templates:read`: List and read templates
- `workspace:templates:write`: Update template modifications via API
- `render:generate`: Generate images, PDFs, and videos
- `mcp:access`: Access via Model Context Protocol
- `offline_access`: Long-lived refresh tokens

## Use the access token

Send it as a bearer token to the API:

```http
GET /v1/studio/templates HTTP/1.1
Host: api.orshot.com
Authorization: Bearer <access_token>
```

API keys use the same header format. API reference:
https://orshot.com/docs/api-reference

## MCP server

For tool-based access, connect to `https://mcp.orshot.com/mcp` using the
same OAuth flow. Server card:
https://orshot.com/.well-known/mcp/server-card.json

## Errors

| Status | Meaning | What to do |
| ------ | ------- | ---------- |
| 401 | Missing or invalid token | Re-run the auth flow or check the key |
| 403 | Token lacks the required scope | Request the scope listed above |
| 429 | Rate limited | Back off and retry with the Retry-After header |

## Revocation

Users can revoke agent access and rotate API keys any time from
https://orshot.com/dashboard. Refresh tokens stop working once access is
revoked.