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:

Environment	Prefix	Purpose
Live	`ak_live_`	Production use — real encoding, real billing
Test	`ak_test_`	Development and testing — sandbox environment

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

const created = await client.apiKeys.create({
  name: "Production Server",
  description: "Backend API key for video uploads",
  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 Server",
    description="Backend API key for video uploads",
    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 Server",
	Description: "Backend API key for video uploads",
	Environment: transcodely.APIKeyEnvironmentLive,
})
// created.PlainText holds the full key — returned only here. Store it now.
fmt.Println(created.Key.GetId(), created.PlainText)

{
  "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.

The official SDKs take the key as an explicit constructor argument. The conventional environment variable is TRANSCODELY_API_KEY — load it once at startup and pass it in:

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

const client = new Transcodely({ apiKey: process.env.TRANSCODELY_API_KEY! });

client = Transcodely(api_key=os.environ["TRANSCODELY_API_KEY"])

client, err := transcodely.New(os.Getenv("TRANSCODELY_API_KEY"))

Key Identification

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

Field	Example	Purpose
`key_prefix`	`ak_live_`	Identifies the environment
`key_hint`	`...z7w6`	Last 4 characters for support lookups

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

const created = await client.apiKeys.create({
  name: "CI/CD Pipeline Key",
  environment: APIKeyEnvironment.API_KEY_ENVIRONMENT_TEST,
  expiresAt: Timestamp.fromDate(new Date("2026-06-01T00:00:00Z")),
});

created = client.api_keys.create(
    name="CI/CD Pipeline Key",
    environment="test",
    expires_at="2026-06-01T00:00:00Z",
)

created, err := client.APIKeys.Create(ctx, &transcodely.APIKeyCreateParams{
	Name:        "CI/CD Pipeline Key",
	Environment: transcodely.APIKeyEnvironmentTest,
	ExpiresAt:   timestamppb.New(time.Date(2026, 6, 1, 0, 0, 0, 0, time.UTC)),
})

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

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

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

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

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

for await (const apiKey of client.apiKeys.list({
  environment: APIKeyEnvironment.API_KEY_ENVIRONMENT_LIVE,
  includeRevoked: false,
  pagination: { limit: 20 },
}).autoPage()) {
  console.log(apiKey.id, apiKey.keyHint);
}

for api_key in client.api_keys.list(limit=20).auto_paging_iter():
    print(api_key.id, api_key.key_hint)

iter := client.APIKeys.List(ctx, &transcodely.APIKeyListParams{
	Environment:    transcodely.APIKeyEnvironmentLive.Enum(),
	IncludeRevoked: false,
	Pagination:     &transcodely.PaginationRequest{Limit: 20},
})
for iter.Next() {
	apiKey := iter.Current()
	fmt.Println(apiKey.GetId(), apiKey.GetKeyHint())
}
if err := iter.Err(); err != nil {
	log.Fatal(err)
}

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

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

#API Keys

#Environments

#Creating an API Key

#Using API Keys

#Key Identification

#Expiration

#Revoking Keys

#Listing Keys

#Security Best Practices