Skip to content

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/login

This endpoint has two modes:

  • Web (default): reads { provider, redirectTo } from the request body. The provider-generated CSRF state is stored in an encrypted cookie for validation on callback.
  • CLI: reads provider, redirect_uri, and state from query params. The CLI manages its own CSRF state, so no cookie is set.

Request Body (Web) ​

FieldTypeRequiredDescription
provider'github' | 'google'YesOAuth provider
redirectTostringNoPost-auth redirect path (default: /auth/callback)

Query Parameters (CLI) ​

ParamTypeRequiredDescription
provider'github' | 'google'YesOAuth provider
redirect_uristringYesLocalhost callback. Must be http://127.0.0.1 or http://localhost, port 9876-9899, path /callback.
statestringNoCaller-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 ​

json
{
  "url": "https://github.com/login/oauth/authorize?client_id=...",
  "state": "csrf-state-token"
}

Example ​

bash
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"provider": "github"}'

Error Codes ​

StatusCondition
400Invalid provider, or (CLI) redirect_uri is not an allowed localhost callback
429Rate 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/verify

This 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/refresh when they expire.

Request Body ​

FieldTypeRequiredDescription
codestringConditionalOAuth authorization code (code flow)
statestringConditionalCSRF state token (required with code in web mode; CLI manages its own state)
accessTokenstringConditionalAccess token (magic link / implicit flow)
refreshTokenstringNoRefresh token (magic link / implicit flow)
source'cli'NoWhen set to 'cli', returns tokens instead of setting a cookie

Either code (+ state in web mode) OR accessToken must be provided.

Response (Web) ​

json
{
  "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) ​

json
{
  "user": { "id": "uuid", "email": "user@example.com", "provider": "github", "providerAccountId": "12345", "avatarUrl": null },
  "tokens": {
    "accessToken": "...",
    "refreshToken": "...",
    "expiresAt": 1735689600
  }
}

Error Codes ​

StatusCondition
400Neither code nor accessToken provided
403Invalid or missing CSRF state token (web code flow)
429Rate 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/refresh

Request Body ​

FieldTypeRequiredDescription
refreshTokenstringYesRefresh token from a prior verify (CLI) response

Response ​

json
{
  "accessToken": "...",
  "refreshToken": "...",
  "expiresAt": 1735689600
}

Error Codes ​

StatusCondition
400refreshToken missing
401Session expired / refresh not possible
429Rate limit exceeded

Auth ​

Public endpoint. Rate limited: 10 requests per minute per IP.


Send a passwordless magic link email.

POST /api/auth/magic-link

Request Body ​

FieldTypeRequiredDescription
emailstringYesEmail address to send the magic link to
redirectTostringNoPost-auth redirect path (default: /auth/callback)

Response ​

json
{ "sent": true }

Returns 200 regardless of whether the email exists (prevents enumeration).

Error Codes ​

StatusCondition
400email missing
429Rate 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 CSRF state cookie is generated and validated by the auth module itself.
  • Leg 2 (?code=...): the provider redirects back here; the module validates its own state, 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 ​

ParamTypeRequiredDescription
redirectstringNoPost-auth in-app redirect path (must start with /; default /)
cli_redirectstringNoCLI callback URL. When present, sign-in completes by redirecting here with a one-time code instead of setting a web cookie
cli_statestringNoCSRF state echoed back on the CLI callback

Errors ​

StatusCondition
400:provider is not github or google
404Not running on the managed pair

On provider-side failure the handler redirects to /auth/login?error=oauth rather than returning an error status.


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 ​

ParamTypeRequiredDescription
tokenstringYesSingle-use, 1-hour magic-link / invite token
redirectstringNoPost-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
FieldTypeRequiredDescription
emailstringYesMust match the configured review address
passwordstringYesMust 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/me

Response ​

json
{
  "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/logout

Response ​

json
{ "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/profile

Request Body ​

FieldTypeRequiredDescription
displayNamestringNoDisplay name. Trimmed; must be 1-100 characters.
theme'light' | 'dark' | 'system'NoUI theme preference.

At least one field must be provided.

Response ​

Returns the updated profile row.

Error Codes ​

StatusCondition
400Invalid 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/avatar

Request ​

multipart/form-data with a file field. Allowed types: image/jpeg, image/png, image/webp, image/gif. Maximum size: 2 MB.

Response ​

json
{ "avatarUrl": "data:image/webp;base64,..." }

Error Codes ​

StatusCondition
400Missing 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/avatar

Response ​

json
{ "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-workspaces

Response ​

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-plans

Response ​

json
[
  { "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/profile

Response ​

json
{ "deleted": true }

Error Codes ​

All three are 409 and carry a machine-readable data.code; the account is left untouched.

data.codeCondition
ownership_transfer_requiredAn owned secondary workspace still has other members (data.workspaces lists their ids)
active_subscriptionAn owned workspace has a subscription that is still billing (data.workspaces lists their ids); cancel it first
account_delete_blockedThe account could not be removed because other records still reference it

Auth ​

Requires valid session.


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 /api/oauth/consent

Returns the requesting client and the signed-in user's workspace and project tree with per-entry eligibility:

json
{
  "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
FieldTypeRequiredDescription
decision'approve' | 'deny'YesThe user's choice
workspaceIdstringWith approveWorkspace to grant
projectIdstringWith approveProject 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.

StatusCondition
400Flow expired, missing fields, or the project is not eligible (no repository / no GitHub installation)
402Billing locked on the selected workspace
403Cross-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.

MethodPathPurpose
GET/.well-known/oauth-protected-resource/api/mcp/remoteRFC 9728 protected-resource metadata (also served at /.well-known/oauth-protected-resource)
GET/.well-known/oauth-authorization-serverRFC 8414 authorization-server metadata (also served at /.well-known/openid-configuration as an alias; Studio issues no ID tokens)
POST/oauth/registerDynamic 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/authorizeAuthorization 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/tokenToken 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.

Released under the AGPL-3.0 License. Privacy