#Authentication

Every request to the Transcodely API must include a valid API key. Keys are scoped to an App within your Organization and determine which resources you can access.

#API Key Format

Transcodely API keys follow a prefixed format that tells you the environment at a glance:

• Live keys (ak_live_) authenticate against production resources. Jobs created with live keys are billed.
• Test keys (ak_test_) authenticate against the sandbox environment. Use these for development and testing. Test jobs are not billed.

#Sending Authenticated Requests

Include your API key in the Authorization header using the Bearer scheme:

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/List 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{}'

All API requests use POST with Content-Type: application/json. The Transcodely API is built on Connect-RPC, so every endpoint follows the /{package}.{Service}/{Method} URL pattern.

#Required Headers

#Creating API Keys

You can create API keys from the Transcodely dashboard or programmatically via the API:

curl -X POST https://api.transcodely.com/transcodely.v1.APIKeyService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Production API Key",
    "description": "Used by the video pipeline service",
    "environment": "live"
  }'

The response includes the full secret exactly once. Store it securely — you cannot retrieve it again:

{
  "api_key": {
    "id": "ak_r4s5t6u7v8w9x0y1",
    "name": "Production API Key",
    "key_prefix": "ak_live_",
    "key_hint": "StUv",
    "environment": "live",
    "created_at": "2026-02-28T10:30:00Z"
  },
  "secret": "ak_live_AbCdEf1234567890GhIjKlMnOpQrStUv"
}

#Revoking Keys

If a key is compromised, revoke it immediately. Revoked keys cannot be used for authentication:

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

#Security Best Practices

• Never embed keys in client-side code. API keys should only be used in server-side applications.
• Use test keys for development. Switch to live keys only for production deployments.
• Rotate keys periodically. Create a new key, update your services, then revoke the old one.
• Set expiration dates on keys that are used for temporary integrations or CI/CD pipelines.
• Use separate keys per service. If one key is compromised, you only need to rotate that key.
• Store keys in environment variables or a secrets manager — never in source code or configuration files committed to version control.

#Error Responses

If authentication fails, the API returns a Connect-RPC unauthenticated error:

{
  "code": "unauthenticated",
  "message": "Invalid or missing API key"
}

Common causes: