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. Every key carries an ak_ prefix, and its full secret is shown only once — at creation.

Creating an API Key

Create a key with a human-readable name and an optional description. The response includes the full secret exactly once — capture it immediately, because only the key_prefix and key_hint are retrievable afterward.

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

const created = await client.apiKeys.create({
  name: "Production Server",
  description: "Backend API key for video uploads",
});
// 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",
)
# 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",
})
// 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_x9y8z",
    "key_hint": "l5k4",
    "scopes": [],
    "is_revoked": false,
    "created_at": "2026-01-15T10:30:00Z"
  },
  "secret": "ak_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. 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 "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"))

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:

Field	Example	Purpose
`key_prefix`	`ak_x9y8z`	First 8 characters of the secret — a per-key value, not a constant scheme tag
`key_hint`	`l5k4`	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 "Content-Type: application/json" 
  -d '{
    "name": "CI/CD Pipeline Key",
    "expires_at": "2026-06-01T00:00:00Z"
  }'

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

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

created, err := client.APIKeys.Create(ctx, &transcodely.APIKeyCreateParams{
	Name:      "CI/CD Pipeline Key",
	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 "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

List the keys for the current app, optionally including revoked ones. Results are paginated, and the SDKs auto-page so you can iterate every key without handling tokens yourself.

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

for await (const apiKey of client.apiKeys.list({
  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{
	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.
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

#Creating an API Key

#Using API Keys

#Key Identification

#Expiration

#Revoking Keys

#Listing Keys

#Security Best Practices