Skip to main content

OAuth 2.0

OAuth 2.0 lets third-party applications access the Vidocu API on behalf of users, without handling their credentials directly.

When to use OAuth vs API keys​

API KeysOAuth 2.0
Use caseYour own server-to-server integrationThird-party apps acting on behalf of users
Auth scopeFull workspace accessGranular, user-approved scopes
Who creates itWorkspace adminUser approves via consent screen
Token formatvdo_live_*vdo_oat_* (access) / vdo_ort_* (refresh)
LifetimeUntil revokedAccess: 1 hour, Refresh: 30 days

Use API keys when you're building your own integration and control both sides.

Use OAuth when you're building an app that other Vidocu users will connect to — like a Zapier integration, a CMS plugin, or a third-party dashboard.

How it works​

Vidocu implements the Authorization Code flow with optional PKCE (Proof Key for Code Exchange):

1. Your app redirects user to Vidocu's consent screen
2. User approves access and selects a workspace
3. Vidocu redirects back to your app with an authorization code
4. Your app exchanges the code for access + refresh tokens
5. Use the access token to call the API
6. Refresh the token when it expires
┌──────────┐     ┌──────────┐     ┌──────────┐
│ Your App │     │   User   │     │  Vidocu  │
└────┬─────┘     └────┬─────┘     └────┬─────┘
     │  Redirect to   │                │
     │  /oauth/authorize               │
     │────────────────>│                │
     │                 │  Show consent  │
     │                 │───────────────>│
     │                 │  Approve       │
     │                 │───────────────>│
     │  Redirect with code             │
     │<────────────────────────────────│
     │  Exchange code for tokens       │
     │────────────────────────────────>│
     │  Access + Refresh tokens        │
     │<────────────────────────────────│
     │  API calls with access token    │
     │────────────────────────────────>│

Next steps​