#API Keys

API keys are the primary authentication mechanism for the Transcodely API. Each key is scoped to a single App and grants access to all resources within that app.

#Environments

Transcodely API keys come in two environments:

Test keys behave identically to live keys but operate in an isolated sandbox. Use test keys during development and switch to live keys when you go to production.

#Creating an API Key

curl -X POST https://api.transcodely.com/transcodely.v1.APIKeyService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Production Server",
    "description": "Backend API key for video uploads",
    "environment": "live"
  }'

{
  "api_key": {
    "id": "ak_a1b2c3d4e5f6g7h8",
    "name": "Production Server",
    "description": "Backend API key for video uploads",
    "key_prefix": "ak_live_",
    "key_hint": "...z7w6",
    "environment": "live",
    "scopes": [],
    "is_revoked": false,
    "created_at": "2026-01-15T10:30:00Z"
  },
  "secret": "ak_live_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4"
}

Important: The full API key secret is only returned once at creation. Store it securely — you cannot retrieve it again. If you lose it, revoke the key and create a new one.

#Using API Keys

Pass your API key as a Bearer token in the Authorization header:

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Create 
  -H "Authorization: Bearer ak_live_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{ ... }'

The API key determines which app the request is scoped to. All resources created with a key belong to that key’s app.

#Key Identification

After creation, the full secret is never returned again. Instead, two safe-to-display fields are available for identification:

These fields are safe to display in logs, dashboards, and admin interfaces.

#Expiration

API keys can optionally be created with an expiration time:

curl -X POST https://api.transcodely.com/transcodely.v1.APIKeyService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "CI/CD Pipeline Key",
    "environment": "test",
    "expires_at": "2026-06-01T00:00:00Z"
  }'

Keys without an expires_at never expire. Expired keys are automatically rejected at authentication time.

#Revoking Keys

Revoke a key immediately when it is compromised or no longer needed:

curl -X POST https://api.transcodely.com/transcodely.v1.APIKeyService/Revoke 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "id": "ak_a1b2c3d4e5f6g7h8",
    "reason": "Key exposed in public repository"
  }'

Revocation is immediate and irreversible. Any in-flight requests using the revoked key will fail with a 401 Unauthenticated error.

#Listing Keys

curl -X POST https://api.transcodely.com/transcodely.v1.APIKeyService/List 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "environment": "live",
    "include_revoked": false,
    "pagination": { "limit": 20 }
  }'

Each key in the response includes a last_used_at timestamp, which is useful for identifying stale keys that should be cleaned up.

#Security Best Practices

1. Never commit keys to version control. Use environment variables or a secrets manager.
2. Use test keys for development. Switch to live keys only in production environments.
3. Rotate keys periodically. Create a new key, update your systems, then revoke the old one.
4. Set expiration dates on keys used for temporary access (CI/CD, contractors, demos).
5. Use descriptive names so you can identify what each key is used for.
6. Monitor last_used_at to find and revoke unused keys.
7. Revoke immediately if a key is exposed. There is no “undo” — create a new key instead.