Authentication API
Studio uses cookie-based session authentication. The OAuth flow starts with a redirect URL, completes with code/token exchange, and stores an encrypted httpOnly cookie.
Internal API
These are internal endpoints, not a public external API. They are consumed by the Studio SPA (cookie / encrypted-session based) and the Contentrain CLI (token based, via source: 'cli'). Shapes may change without notice.
Login (OAuth Redirect)
Get an OAuth redirect URL for GitHub or Google.
POST /api/auth/loginThis endpoint has two modes:
- Web (default): reads
{ provider, redirectTo }from the request body. The provider-generated CSRFstateis stored in an encrypted cookie for validation on callback. - CLI: reads
provider,redirect_uri, andstatefrom query params. The CLI manages its own CSRF state, so no cookie is set.
Request Body (Web)
| Field | Type | Required | Description |
|---|---|---|---|
provider | 'github' | 'google' | Yes | OAuth provider |
redirectTo | string | No | Post-auth redirect path (default: /auth/callback) |
Query Parameters (CLI)
| Param | Type | Required | Description |
|---|---|---|---|
provider | 'github' | 'google' | Yes | OAuth provider |
redirect_uri | string | Yes | Localhost callback. Must be http://127.0.0.1 or http://localhost, port 9876-9899, path /callback. |
state | string | No | Caller-supplied CSRF state. Falls back to the provider-generated state when omitted. |
CLI mode activates automatically when both provider and redirect_uri query params are present.
Response
{
"url": "https://github.com/login/oauth/authorize?client_id=...",
"state": "csrf-state-token"
}Example
curl -X POST http://localhost:3000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"provider": "github"}'Error Codes
| Status | Condition |
|---|---|
400 | Invalid provider, or (CLI) redirect_uri is not an allowed localhost callback |
429 | Rate limit exceeded |
Managed pair
On the managed auth pair, url points at GET /api/auth/oauth/:provider (see Managed-Pair Interactive Sign-In) and no state is returned for the web flow -- CSRF state is handled by the OAuth module's own cookie.
Auth
Public endpoint. Rate limited: 10 requests per minute per IP.
Verify (Token Exchange)
Exchange an OAuth authorization code or magic link tokens for a session.
POST /api/auth/verifyThis endpoint has two modes:
- Web (default): stores tokens in an encrypted httpOnly cookie and returns
{ user }. - CLI (
source: 'cli'): returns{ user, tokens }and does not set a cookie. The CLI stores the tokens locally and calls/api/auth/refreshwhen they expire.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
code | string | Conditional | OAuth authorization code (code flow) |
state | string | Conditional | CSRF state token (required with code in web mode; CLI manages its own state) |
accessToken | string | Conditional | Access token (magic link / implicit flow) |
refreshToken | string | No | Refresh token (magic link / implicit flow) |
source | 'cli' | No | When set to 'cli', returns tokens instead of setting a cookie |
Either code (+ state in web mode) OR accessToken must be provided.
Response (Web)
{
"user": {
"id": "uuid",
"email": "user@example.com",
"avatarUrl": "https://avatars.githubusercontent.com/u/123",
"provider": "github",
"providerAccountId": "12345"
}
}The server sets an encrypted httpOnly cookie (contentrain-session) containing the user id, access token, refresh token, and expiration timestamp. The cookie lasts 7 days from the last write (sign-in or token refresh), so only 7 idle days sign a user out.
Response (CLI)
{
"user": { "id": "uuid", "email": "user@example.com", "provider": "github", "providerAccountId": "12345", "avatarUrl": null },
"tokens": {
"accessToken": "...",
"refreshToken": "...",
"expiresAt": 1735689600
}
}Error Codes
| Status | Condition |
|---|---|
400 | Neither code nor accessToken provided |
403 | Invalid or missing CSRF state token (web code flow) |
429 | Rate limit exceeded |
Auth
Public endpoint. Rate limited: 10 requests per minute per IP.
Refresh (Token Refresh)
Exchange a refresh token for a new access + refresh token pair. Primarily for the CLI -- web clients are auto-refreshed by the auth middleware from the encrypted cookie.
POST /api/auth/refreshRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
refreshToken | string | Yes | Refresh token from a prior verify (CLI) response |
Response
{
"accessToken": "...",
"refreshToken": "...",
"expiresAt": 1735689600
}Error Codes
| Status | Condition |
|---|---|
400 | refreshToken missing |
401 | Session expired / refresh not possible |
429 | Rate limit exceeded |
Auth
Public endpoint. Rate limited: 10 requests per minute per IP.
Magic Link
Send a passwordless magic link email.
POST /api/auth/magic-linkRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address to send the magic link to |
redirectTo | string | No | Post-auth redirect path (default: /auth/callback) |
Response
{ "sent": true }Returns 200 regardless of whether the email exists (prevents enumeration).
Error Codes
| Status | Condition |
|---|---|
400 | email missing |
429 | Rate limit exceeded |
Auth
Public endpoint. Rate limited: 5 requests per minute per IP.
Managed-Pair Interactive Sign-In
Managed pair only
These are browser redirect endpoints, not JSON APIs. They exist only on the managed auth pair and return 404 on the self-hosted (Supabase) pair, where GoTrue owns OAuth and magic links. They are the interactive counterparts to the JSON POST /api/auth/login and POST /api/auth/magic-link documented above -- the browser (or CLI) navigates to them directly and follows the redirects.
OAuth Sign-In
Runs the full OAuth authorization-code dance for GitHub or Google in two legs against the same URL.
GET /api/auth/oauth/:provider:provider must be github or google.
- Leg 1 (no
code): stashes flow context in a sealed cookie, then redirects the browser to the provider's consent screen. A CSRFstatecookie is generated and validated by the auth module itself. - Leg 2 (
?code=...): the provider redirects back here; the module validates its ownstate, exchanges the code, links or creates the user, and then either sets the web session cookie and redirects into the app, or -- for a CLI flow -- redirects to the CLI callback with a one-time code.
Query Parameters
| Param | Type | Required | Description |
|---|---|---|---|
redirect | string | No | Post-auth in-app redirect path (must start with /; default /) |
cli_redirect | string | No | CLI callback URL. When present, sign-in completes by redirecting here with a one-time code instead of setting a web cookie |
cli_state | string | No | CSRF state echoed back on the CLI callback |
Errors
| Status | Condition |
|---|---|
400 | :provider is not github or google |
404 | Not running on the managed pair |
On provider-side failure the handler redirects to /auth/login?error=oauth rather than returning an error status.
Magic Link / Invite Verify
Landing endpoint for a magic-link or invite email. Consumes the single-use token server-side, sets the session cookie, and 302s into the app. A server-side GET (rather than a client POST) keeps the flow working across browsers and devices.
GET /api/auth/magic/verify?token=<token>&redirect=/Query Parameters
| Param | Type | Required | Description |
|---|---|---|---|
token | string | Yes | Single-use, 1-hour magic-link / invite token |
redirect | string | No | Post-auth in-app redirect path (must start with /; default /) |
A missing or invalid/consumed token redirects to /auth/login?error=magic-link (no error status).
Auth
Public endpoint on the managed pair. Rate limited: 10 requests per minute per IP. Returns 404 on the self-hosted pair, 429 when rate limited.
Review Login
Password sign-in for a single operator-configured account, used for app-directory review. It exists only when the operator sets both NUXT_REVIEW_ACCOUNT_EMAIL and NUXT_REVIEW_ACCOUNT_PASSWORD (at least 16 characters) on the managed pair; otherwise the route answers 404 as if it did not exist.
POST /api/auth/review-login| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Must match the configured review address |
password | string | Yes | Must match the configured password |
Returns { "ok": true } and sets the session cookie. Errors: 401 wrong credentials, 404 not enabled (or not the managed pair), 429 rate limited (5 requests per minute per IP). Public endpoint.
Current User
Get the currently authenticated user with profile data.
GET /api/auth/meResponse
{
"user": {
"id": "uuid",
"email": "user@example.com",
"avatarUrl": "https://avatars.githubusercontent.com/u/123",
"provider": "github",
"providerAccountId": "12345",
"displayName": "Jane Doe",
"theme": "system"
}
}avatarUrl, displayName, and theme are merged from the user's profile row (theme defaults to system).
Auth
Requires valid session.
Logout
End the current session and clear the session cookie.
POST /api/auth/logoutResponse
{ "ok": true }Auth
Requires a valid session cookie. Logout is not on the public-path list, so a request without a session is rejected with 401 by the auth middleware. On the managed pair it also revokes the refresh-token family server-side (best effort; the cookie is cleared regardless).
Update Profile
Update the authenticated user's display name and/or theme.
PATCH /api/profileRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
displayName | string | No | Display name. Trimmed; must be 1-100 characters. |
theme | 'light' | 'dark' | 'system' | No | UI theme preference. |
At least one field must be provided.
Response
Returns the updated profile row.
Error Codes
| Status | Condition |
|---|---|
400 | Invalid display name length, invalid theme value, or no fields to update |
Auth
Requires valid session.
Upload Avatar
Upload a custom avatar image. The image is resized to 256x256 WebP and stored as a base64 data URI on the profile.
POST /api/profile/avatarRequest
multipart/form-data with a file field. Allowed types: image/jpeg, image/png, image/webp, image/gif. Maximum size: 2 MB.
Response
{ "avatarUrl": "data:image/webp;base64,..." }Error Codes
| Status | Condition |
|---|---|
400 | Missing file, unsupported content type, or file larger than 2 MB |
Auth
Requires valid session.
Remove Avatar
Remove the custom avatar, reverting to the OAuth provider avatar.
DELETE /api/profile/avatarResponse
{ "avatarUrl": null }Auth
Requires valid session.
Owned Workspaces
List the owned secondary workspaces that currently block account deletion because they still have other members. The same check backs DELETE /api/profile, which refuses with 409 while this list is non-empty.
GET /api/profile/owned-workspacesResponse
An array of workspace objects (each including its workspace_members). Workspaces with no members other than the owner are filtered out. Transfer ownership with Transfer Ownership before deleting.
Auth
Requires valid session.
Ending Plans
List owned workspaces whose paid plan is already set to end with its billing period. The account screen shows this before deletion: deleting the account ends access immediately rather than at the period's end.
GET /api/profile/ending-plansResponse
[
{ "workspace_id": "uuid", "ends_at": "2026-12-01T00:00:00.000Z" }
]Auth
Requires valid session.
Delete Account
Permanently delete the authenticated user's account. The user is deleted from auth.users, and a database CASCADE removes profiles, workspaces, members, projects, and all child records. Only after the account is gone does the server clean up CDN storage for every owned workspace's projects (best effort -- a failure leaves orphaned files, never a half-deleted account). The session cookie is cleared.
DELETE /api/profileResponse
{ "deleted": true }Error Codes
All three are 409 and carry a machine-readable data.code; the account is left untouched.
data.code | Condition |
|---|---|
ownership_transfer_required | An owned secondary workspace still has other members (data.workspaces lists their ids) |
active_subscription | An owned workspace has a subscription that is still billing (data.workspaces lists their ids); cancel it first |
account_delete_blocked | The account could not be removed because other records still reference it |
Auth
Requires valid session.
OAuth Consent (Remote MCP)
These two routes back the consent screen at /oauth/consent that AI apps send users to when connecting through the MCP Connector. They are session-protected, managed-pair only (404 otherwise), and work on the pending authorization stored in a short-lived sealed cookie by GET /oauth/authorize. When that cookie is missing or expired both answer 400.
Get Consent Data
GET /api/oauth/consentReturns the requesting client and the signed-in user's workspace and project tree with per-entry eligibility:
{
"client": { "displayHost": "claude.ai", "name": "Claude", "logoUri": null, "loopbackOnly": false },
"scope": "content:read project:metadata",
"scopes": ["content:read", "project:metadata"],
"workspaces": [
{
"id": "uuid", "name": "Acme", "slug": "acme", "role": "owner",
"eligible": true, "reason": null,
"projects": [{ "id": "uuid", "repoFullName": "acme/site", "eligible": true, "reason": null }]
}
]
}reason is null when eligible, otherwise ineligible_no_installation (no GitHub App installation), ineligible_payment_required (billing locked), ineligible_plan (plan lacks api.mcp_cloud_oauth), or, for a project only, ineligible_no_repo. Plain workspace members see only their assigned projects.
Submit Decision
POST /api/oauth/consent| Field | Type | Required | Description |
|---|---|---|---|
decision | 'approve' | 'deny' | Yes | The user's choice |
workspaceId | string | With approve | Workspace to grant |
projectId | string | With approve | Project to grant |
Returns { "redirectTo": "<client redirect URI with code or error>" }; the page performs it as a top-level navigation. A deny redirects with error=access_denied. Approval re-checks project access, GitHub installation, and the plan gate server-side.
| Status | Condition |
|---|---|
400 | Flow expired, missing fields, or the project is not eligible (no repository / no GitHub installation) |
402 | Billing locked on the selected workspace |
403 | Cross-origin request (the Origin header must be Studio's own), no access to the project, or plan without api.mcp_cloud_oauth |
OAuth Server Endpoints (Remote MCP)
Managed pair only
Studio acts as the OAuth 2.1 authorization server for the remote MCP endpoint (/api/mcp/remote) on the managed auth pair; every route below answers 404 on the Supabase pair. MCP clients discover and call these automatically -- you only need them if you are building a client. The user-facing steps are on MCP Connector.
These live at the site root, outside /api/, and need no Studio session.
| Method | Path | Purpose |
|---|---|---|
GET | /.well-known/oauth-protected-resource/api/mcp/remote | RFC 9728 protected-resource metadata (also served at /.well-known/oauth-protected-resource) |
GET | /.well-known/oauth-authorization-server | RFC 8414 authorization-server metadata (also served at /.well-known/openid-configuration as an alias; Studio issues no ID tokens) |
POST | /oauth/register | Dynamic Client Registration (RFC 7591) for clients without a client-ID metadata document. Public clients only (token_endpoint_auth_method: none); 201 with a client_id; rate limited to 10 per minute per IP |
GET | /oauth/authorize | Authorization endpoint. Requires response_type=code and PKCE (code_challenge with S256); optional resource must be the MCP endpoint. Redirects to sign-in, then the consent screen |
POST | /oauth/token | Token endpoint: authorization_code (with code_verifier) and refresh_token grants. Accepts form-encoded or JSON bodies; returns RFC 6749 JSON errors such as invalid_grant |
Supported scopes are content:read, content:write, project:metadata, offline_access, plus media:read and media:write where the deployment has the media stack. A request without scope gets content:read project:metadata. Clients that identify themselves with a URL client_id (client-ID metadata documents) skip registration.
Related Pages
- API Reference Overview -- authentication model
- Architecture -- session management details