Token Management

How to refresh, revoke, and manage OAuth tokens.

Token lifetimes

Token	Lifetime	Format
Access token	1 hour	vdo_oat_*
Refresh token	30 days	vdo_ort_*
Authorization code	10 minutes	Single-use

Refreshing tokens

When an access token expires, use the refresh token to get a new pair:

curl -X POST https://api.vidocu.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "vdo_ort_...",
    "client_id": "vdo_client_abc123",
    "client_secret": "vdo_secret_xyz789"
  }'

Response:

{
  "access_token": "vdo_oat_new...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "vdo_ort_new...",
  "scope": "videos:read analyze:write"
}

Refresh token rotation

Each refresh produces a new refresh token and invalidates the old one. Always store and use the latest refresh token from the response.

Reuse detection

If a previously-rotated refresh token is used again, Vidocu assumes token theft and revokes all tokens for that user-app pair. Both the user and app will need to re-authorize.

Revoking tokens

To revoke a token (e.g., on user logout):

curl -X POST https://api.vidocu.ai/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "token": "vdo_oat_...",
    "token_type_hint": "access_token"
  }'

Parameter	Required	Description
token	Yes	The token to revoke
token_type_hint	No	access_token or refresh_token — helps the server find the token faster

The endpoint always returns 200, even if the token was already invalid (per RFC 7009).

User-initiated revocation

Users can revoke app access from their Connected Apps tab in the dashboard. This immediately invalidates all access and refresh tokens for that app.

Security best practices

• Store tokens securely — never expose them in client-side code, URLs, or logs
• Use short-lived access tokens — the 1-hour lifetime limits exposure if a token is leaked
• Always use the latest refresh token — discard the old one after each refresh
• Implement PKCE for public clients — prevents authorization code interception
• Validate the state parameter — prevents CSRF attacks on the callback
• Use HTTPS for all redirect URIs in production