How does OAuth work with Orshot?

Orshot uses OAuth 2.0 to let third-party apps access user data securely. Users explicitly grant your app permission to specific workspaces and actions — your app never sees their password.

Supported Grant Types#

Both flows result in an access token and refresh token that your app uses to call the Orshot API.

The Big Picture#

┌──────────┐     1. Redirect to Orshot     ┌──────────┐
│          │ ───────────────────────────▶  │          │
│ Your App │                               │  Orshot  │
│          │  ◀─── 2. User approves ────── │  Consent │
│          │       (redirect with code)    │  Screen  │
└──────────┘                               └──────────┘
     │
     │ 3. Exchange code for tokens
     │    (POST /v1/oauth/token)
     ▼
┌──────────┐
│  Orshot  │
│   API    │ ◀── 4. Use access token to call API
└──────────┘

Endpoints#

All OAuth endpoints are relative to https://api.orshot.com.

Token Lifecycle#

• Access tokens expire in 15 minutes
• Refresh tokens expire in 30 days
• Use refresh tokens to get new access tokens without re-prompting the user
• Refresh tokens are rotated on each use — always store the new one from the response

See Token Management for details on refreshing and revoking tokens.

Workspace-Scoped Access#

Orshot access is always scoped to specific workspaces. When a user authorizes your app, they choose which workspaces to grant access to. Your tokens will only work for those workspaces.

If a user later removes a workspace from the grant, existing tokens for that workspace are automatically revoked.

Development Mode & Sandbox#

All apps start in development mode (private). While in this mode:

• Only the app owner and explicitly added test users can authorize and use the app
• The consent screen shows an "unverified app" warning to test users
• API calls from unauthorized users return a sandbox_restricted error

Once you publish your app, sandbox restrictions are removed and any Orshot user can authorize it. See Register Your App for details.

Discovery Endpoint#

MCP-compatible clients and other tools can auto-discover Orshot's OAuth configuration:

curl https://api.orshot.com/.well-known/oauth-authorization-server

This returns all endpoints, supported scopes, grant types, and PKCE requirements per RFC 8414.