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 so they’re easy to recognize at a glance:

Prefix	Example
`ak_`	`ak_AbCdEf1234567890GhIjKlMnOpQrStUv`

Every key is scoped to a single App within your Organization and grants access to all resources in that app.

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

const created = await client.apiKeys.create({
  name: "Production API Key",
  description: "Used by the video pipeline service",
});
// 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",
)
# 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",
})
// 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_",
    "key_hint": "StUv",
    "created_at": "2026-02-28T10:30:00Z"
  },
  "secret": "ak_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.
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_`
Revoked key	The key has been revoked and can no longer be used

#Authentication

#API Key Format

#Sending Authenticated Requests

#Required Headers

#Creating API Keys

#Revoking Keys

#Security Best Practices

#Error Responses