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:

Environment	Prefix	Example
Production	`ak_live_`	`ak_live_AbCdEf1234567890GhIjKlMnOpQrStUv`
Sandbox	`ak_test_`	`ak_test_AbCdEf1234567890GhIjKlMnOpQrStUv`

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 '{}'

import { Transcodely } from "transcodely";

// The SDK sends the Authorization: Bearer header for you.
const client = new Transcodely({ apiKey: process.env.TRANSCODELY_API_KEY! });

for await (const job of client.jobs.list({}).autoPage()) {
  console.log(job.id, job.status);
}

import os
from transcodely import Transcodely

# The SDK sends the Authorization: Bearer header for you.
with Transcodely(api_key=os.environ["TRANSCODELY_API_KEY"]) as client:
    for job in client.jobs.list().auto_paging_iter():
        print(job.id, job.status)

// The SDK sends the Authorization: Bearer header for you.
client, err := transcodely.New(os.Getenv("TRANSCODELY_API_KEY"))
if err != nil {
	log.Fatal(err)
}

iter := client.Jobs.List(ctx, &transcodely.JobListParams{})
for iter.Next() {
	job := iter.Current()
	fmt.Println(job.GetId(), job.GetStatus())
}
if err := iter.Err(); err != nil {
	log.Fatal(err)
}

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

Header	Value	Required
`Authorization`	`Bearer {{API_KEY}}`	Yes
`Content-Type`	`application/json`	Yes
`X-Idempotency-Key`	Unique string (max 128 chars)	Optional

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"
  }'

const created = await client.apiKeys.create({
  name: "Production API Key",
  description: "Used by the video pipeline service",
  environment: APIKeyEnvironment.API_KEY_ENVIRONMENT_LIVE,
});
// created.secret holds the full key — returned only here. Store it now.
console.log(created.apiKey?.id, created.secret);

created = client.api_keys.create(
    name="Production API Key",
    description="Used by the video pipeline service",
    environment="live",
)
# created.secret holds the full key — returned only here. Store it now.
print(created.api_key.id, created.secret)

created, err := client.APIKeys.Create(ctx, &transcodely.APIKeyCreateParams{
	Name:        "Production API Key",
	Description: "Used by the video pipeline service",
	Environment: transcodely.APIKeyEnvironmentLive,
})
// created.PlainText holds the full key — returned only here. Store it now.
fmt.Println(created.Key.GetId(), created.PlainText)

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"
  }'

const apiKey = await client.apiKeys.revoke("ak_r4s5t6u7v8w9x0y1");

api_key = client.api_keys.revoke("ak_r4s5t6u7v8w9x0y1")

err := client.APIKeys.Revoke(ctx, "ak_r4s5t6u7v8w9x0y1")

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:

Error	Cause
Missing `Authorization` header	No API key provided in the request
Invalid key format	The key does not start with `ak_live_` or `ak_test_`
Revoked key	The key has been revoked and can no longer be used
Wrong environment	Using a test key against a live-only endpoint, or vice versa

#Authentication

#API Key Format

#Sending Authenticated Requests

#Required Headers

#Creating API Keys

#Revoking Keys

#Security Best Practices

#Error Responses