OAuth

Authorization Code + PKCE. Same scopes as API keys.

Hosted MCP uses this flow (Cursor, Claude, VS Code, Windsurf, and other OAuth-capable clients). You do not paste an API key into MCP config when Connect works. The HTTP /v1 API keeps keys — see Authentication.

Issuer

https://api.braiv.co

Discovery:

• GET https://api.braiv.co/.well-known/oauth-authorization-server
• GET https://api.braiv.co/.well-known/oauth-protected-resource

MCP clients also read protected-resource metadata from https://mcp.braiv.co/.well-known/oauth-protected-resource, which points at this issuer.

Tokens

Token exchange produces the same ApiPrincipal shape the API uses for keys:

{
  subjectUid: string
  workspaceId: string | null
  scopes: string[]
  auth: "oauth"
}

/v1 accepts Authorization: Bearer oat_… access tokens, including Braiv Speech (/v1/voices, /v1/text-to-speech). Routes never treat a Firebase ID token as an API credential.

Sign in on the authorize page with the same Google or email/password account you use in Studio. If your account has one or more team workspaces, Braiv shows a workspace picker after sign-in so you can bind the token to Personal or a team library. Accounts with only a personal library skip that step. Refresh tokens keep the same workspaceId.

Customer setup

See MCP for install snippets per client (Cursor, Claude, VS Code, Windsurf, and others).