Authorization Code Flow

Step-by-step guide to implementing OAuth 2.0 with the Vidocu API.

Step 1: Redirect to authorization

Send the user to the Vidocu authorization endpoint:

GET https://vidocu.ai/oauth/authorize

Query parameters:

Parameter	Required	Description
client_id	Yes	Your app's client ID
redirect_uri	Yes	Must match a registered redirect URI
response_type	Yes	Must be code
scope	Yes	Space-separated list of scopes
state	Recommended	Opaque string for CSRF protection
code_challenge	PKCE	Base64url-encoded SHA-256 of the code verifier
code_challenge_method	PKCE	Must be S256

Example:

https://vidocu.ai/oauth/authorize?\
  client_id=vdo_client_abc123&\
  redirect_uri=https://yourapp.com/callback&\
  response_type=code&\
  scope=videos:read+analyze:write+jobs:read&\
  state=random_csrf_token

With PKCE (required for public clients)

Generate a code verifier and challenge:

// Generate random code verifier
const codeVerifier = crypto.randomBytes(32).toString("base64url");

// Create S256 challenge
const codeChallenge = crypto
  .createHash("sha256")
  .update(codeVerifier)
  .digest("base64url");

Add to the authorization URL:

&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&\
code_challenge_method=S256

Step 2: User approves access

Vidocu shows a consent screen where the user:

1. Sees your app name and requested permissions
2. Selects which workspace to grant access to
3. Approves or denies the request

Step 3: Receive the authorization code

On approval, Vidocu redirects to your redirect_uri with:

https://yourapp.com/callback?code=AUTH_CODE&state=random_csrf_token

On denial:

https://yourapp.com/callback?error=access_denied&state=random_csrf_token

Important: Verify that state matches what you sent in Step 1.

Step 4: Exchange the code for tokens

curl -X POST https://api.vidocu.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE",
    "redirect_uri": "https://yourapp.com/callback",
    "client_id": "vdo_client_abc123",
    "client_secret": "vdo_secret_xyz789"
  }'

For public clients using PKCE, replace client_secret with code_verifier:

curl -X POST https://api.vidocu.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE",
    "redirect_uri": "https://yourapp.com/callback",
    "client_id": "vdo_client_abc123",
    "code_verifier": "your_original_code_verifier"
  }'

Response:

{
  "access_token": "vdo_oat_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "vdo_ort_...",
  "scope": "videos:read analyze:write jobs:read"
}

Step 5: Use the access token

curl https://api.vidocu.ai/v1/videos \
  -H "Authorization: Bearer vdo_oat_..."

The access token works exactly like an API key — same endpoints, same response format. The difference is that it's scoped to the permissions the user approved and expires after 1 hour.

Step 6: Refresh when expired

See Token Management for refresh token usage.

Error responses

The token endpoint returns standard OAuth error responses:

{
  "error": {
    "code": "authentication_error",
    "message": "Invalid or expired authorization code"
  }
}

Status	When
400	Missing required fields, unsupported grant_type
401	Invalid client credentials, expired code, bad PKCE verifier