# OAuth Overview

> Understand how OAuth 2.0 works with Orshot

- **URL**: https://orshot.com/docs/developers/oauth-overview

---

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

| Grant Type                                                       | Best For                               | Requires Browser?                 |
| ---------------------------------------------------------------- | -------------------------------------- | --------------------------------- |
| [Authorization Code + PKCE](https://orshot.com/docs/developers/authorization-code) | Web apps, desktop apps, IDE extensions | Yes                               |
| [Device Flow](https://orshot.com/docs/developers/device-flow)                      | CLI tools, devices without browsers    | No (user visits a URL separately) |

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`.

| Endpoint                                  | Method | Purpose                                        |
| ----------------------------------------- | ------ | ---------------------------------------------- |
| `/oauth/authorize`                        | GET    | Authorization consent screen (on `orshot.com`) |
| `/v1/oauth/token`                         | POST   | Exchange code for tokens / refresh tokens      |
| `/v1/oauth/device/code`                   | POST   | Start a device flow                            |
| `/v1/oauth/introspect`                    | POST   | Check if a token is valid                      |
| `/.well-known/oauth-authorization-server` | GET    | Discovery metadata (RFC 8414)                  |

## 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](https://orshot.com/docs/developers/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](https://orshot.com/docs/developers/publishing), sandbox restrictions are removed and any Orshot user can authorize it. See [Register Your App](https://orshot.com/docs/developers/register-app#development-mode) for details.

## Discovery Endpoint

MCP-compatible clients and other tools can auto-discover Orshot's OAuth configuration:```bash
curl https://api.orshot.com/.well-known/oauth-authorization-server
```This returns all endpoints, supported scopes, grant types, and PKCE requirements per [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).