Authenticate with OAuth

Let Gamma users connect their own accounts to your app with the OAuth 2.0 authorization code flow.

The Gamma API accepts OAuth 2.0 Bearer tokens as an alternative to API keys. Use OAuth when your app acts on behalf of your users — each user connects their own Gamma account, and your requests run as that user in the workspace they choose. If you only need to act as yourself, an API key is simpler.

Gamma implements the standard OAuth 2.0 authorization code flow with PKCE, plus:

• Dynamic Client Registration (RFC 7591) — register your app with a single API call, no approval process
• Authorization Server Metadata (RFC 8414) and Protected Resource Metadata (RFC 9728) — full auto-discovery, so MCP clients and OAuth libraries can configure themselves
• Resource Indicators (RFC 8707) — tokens are audience-bound to the API they are for
• Refresh token rotation

Building an MCP server or assistant integration? MCP clients handle this entire flow automatically via the discovery endpoints — see MCP tools reference. This page is for developers implementing the flow directly.

Quick reference

• OAuth is an alternative to API keys: same endpoints, Authorization: Bearer <token> instead of X-API-KEY.
• The authorization server is auth.gamma.app; register your client once with dynamic client registration.
• Always send resource=https://public-api.gamma.app in the authorization request.
• Scopes: generate (full access, default) or gamma:read (metadata only, no credit spend).
• Access tokens last about an hour; refresh tokens rotate on each use and last up to 90 days.
• Tokens are bound to one user and one workspace; requests spend that user's credits.

Endpoints

Endpoint	URL
Protected resource metadata	https://public-api.gamma.app/.well-known/oauth-protected-resource
Authorization server metadata	https://auth.gamma.app/.well-known/oauth-authorization-server
Client registration	POST https://auth.gamma.app/oauth/register
Authorization	GET https://auth.gamma.app/oauth/authorize
Token	POST https://auth.gamma.app/oauth/token
JWKS	https://auth.gamma.app/.well-known/jwks.json
API base	https://public-api.gamma.app/v1.0/...

Gamma implements OAuth 2.0, not OpenID Connect. There is no /.well-known/openid-configuration, no ID tokens, and no userinfo endpoint. Use the access token to call the Gamma API; do not use it as a sign-in mechanism.

Scopes

Scope	Grants
generate	Full API access: generations, edits, exports, themes, folders, reads. Default if no scope is requested.
gamma:read	Read-only access to gamma metadata (title, thumbnail, author, timestamps). Intended for link-preview integrations. Does not spend credits and cannot reach generation endpoints.

Request the minimum scope your app needs. A gamma:read token receives 403 insufficient_scope on any non-read endpoint.

Set up the flow

Step 1: Register your client

One-time setup. No approval needed; you receive credentials immediately:

curl -X POST https://auth.gamma.app/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My App",
    "redirect_uris": ["https://myapp.example.com/oauth/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
  }'

Choosing token_endpoint_auth_method:

• none — public client (SPA, CLI, desktop, mobile). No client secret; PKCE protects the flow.
• client_secret_basic (default) or client_secret_post — confidential client (server-side web app). You receive a client_secret; store it securely and never ship it to a browser.

Save the returned client_id (and client_secret, if any). Registration creates your OAuth client once per app — reuse the same client_id for all your users; do not re-register per user or per run.

Step 2: Send the user to authorize

Generate a PKCE verifier/challenge and a state value, then redirect the user to:

https://auth.gamma.app/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://myapp.example.com/oauth/callback
  &response_type=code
  &resource=https://public-api.gamma.app
  &scope=generate
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_S256_CHALLENGE
  &code_challenge_method=S256

Always include resource=https://public-api.gamma.app. This RFC 8707 resource indicator becomes the token's audience. Tokens minted without it are not valid for the Gamma API. Omitting it is the most common integration mistake.

The user signs in to Gamma, selects a workspace, and consents. Gamma then redirects back to your app:

https://myapp.example.com/oauth/callback?code=AUTH_CODE&state=RANDOM_STATE

Verify state matches before continuing.

Step 3: Exchange the code for tokens

curl -X POST https://auth.gamma.app/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://myapp.example.com/oauth/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=YOUR_PKCE_VERIFIER"

Confidential clients also authenticate here — client_secret in the body for client_secret_post, or HTTP Basic auth for client_secret_basic.

Response

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "generate",
  "refresh_token": "gamma_refresh_..."
}

Authorization codes are single-use and short-lived — exchange them immediately.

Step 4: Call the API

curl -X POST https://public-api.gamma.app/v1.0/generations \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "inputText": "The history of the telescope", "format": "presentation" }'

All API endpoints work identically with OAuth tokens and API keys — same routes, same request and response shapes. Generations and other credit-spending operations consume the authorizing user's credits in the workspace they selected.

Step 5: Refresh the token

Access tokens expire after about an hour. Refresh without user interaction:

curl -X POST https://auth.gamma.app/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=CURRENT_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID"

Refresh tokens rotate. Every refresh returns a new refresh token and invalidates the old one. Persist the newly returned token atomically; if you lose it, the user must re-authorize.

Refresh tokens live up to 90 days. A user whose token has not been refreshed in 90 days must go through the authorization flow again.

Handle errors

The API returns RFC 6750-compliant Bearer errors with a WWW-Authenticate header:

Status	Error	Meaning	What to do
401	invalid_token	Token missing, expired, malformed, or wrong audience	Refresh the access token; if refresh fails, re-run the authorization flow
403	insufficient_scope	Token's scope doesn't cover this endpoint	Request the right scope at authorization time
400 (at authorize/token)	invalid_grant, invalid_target	Bad or expired code, PKCE mismatch, or unsupported resource	Check the resource value and PKCE implementation

Recommended client logic: on 401, attempt one token refresh and retry; if that fails, prompt the user to reconnect.

Best practices

The two highest-impact rules: always send resource=https://public-api.gamma.app at authorization, and always persist the rotated refresh token before discarding the old one.

• Always use PKCE (S256), even for confidential clients. Gamma supports combining PKCE with a client secret.
• Request the minimum scope. Link previews and metadata readers should use gamma:read, not generate.
• Validate state on the callback to prevent CSRF.
• Store tokens securely, server-side where possible. Access tokens are bearer credentials — anyone holding one can act as the user. Never log them or embed them in client-side code.
• Serialize refreshes if multiple workers share a token, so a rotation isn't lost.
• Tokens are user and workspace scoped. A token acts as one user in the one workspace they picked at consent. To work in a different workspace, run the authorization flow again. Design your "Connect Gamma" UX to show which workspace is connected.
• Cache the access token until near expires_in — don't refresh on every request.

FAQ

Can I use OAuth for "Sign in with Gamma"? No — Gamma's OAuth is for API authorization only. There are no ID tokens or userinfo endpoint.

Do OAuth requests cost credits? Same as API key requests: generations, exports, and images consume the authorizing user's credits. gamma:read-scoped metadata reads do not.

Can one token access multiple workspaces? No. One authorization = one user + one workspace. Repeat the flow per workspace.

Related

• Explore the API for the API key alternative and endpoint overview
• Review access and pricing for credit costs and plan details
• MCP tools reference for OAuth in the MCP context