Search Documentation
Search across all documentation pages
API Keys

The API Key object

API keys provide programmatic access to the Transcodely API. Each key is scoped to a specific app and environment.

Important: The full API key secret is only returned once at creation. It cannot be retrieved again. Store it securely.

Base path: transcodely.v1.APIKeyService Requires: X-Organization-ID header on all endpoints.

Attributes

AttributeTypeDescription
idstringUnique identifier. Prefixed with ak_.
namestringHuman-readable name.
descriptionstringDescription of the key’s purpose. Omitted if not set.
key_prefixstringKey prefix for identification (e.g., "ak_live_" or "ak_test_"). Safe to log.
key_hintstringLast 4 characters of the key. Safe for customer support lookups.
environmentenumOne of: live, test.
scopesstring[]Permission scopes. Empty means full access.
last_used_atstringISO 8601 timestamp of last use. Omitted if never used.
expires_atstringISO 8601 expiration timestamp. Omitted if no expiration.
created_atstringISO 8601 timestamp.
is_revokedbooleanWhether the key has been revoked.
revoked_atstringISO 8601 timestamp. Omitted if not revoked.
{
  "id": "ak_x9y8z7w6v5",
  "name": "Production API Key",
  "description": "Used by the video processing pipeline",
  "key_prefix": "ak_live_",
  "key_hint": "n4o5",
  "environment": "live",
  "scopes": [],
  "last_used_at": "2025-02-28T14:22:00Z",
  "expires_at": "2026-01-15T10:30:00Z",
  "created_at": "2025-01-15T10:30:00Z",
  "is_revoked": false
}

Create an API key

Create a new API key. The full secret is returned only in this response — it cannot be retrieved again.

POST /transcodely.v1.APIKeyService/Create

Parameters

ParameterTypeRequiredDescription
namestringYesHuman-readable name (1-255 chars). Example: "Production API Key", "CI/CD".
descriptionstringNoDescription of the key’s purpose (max 1000 chars).
environmentstringYesKey environment: "live" or "test".
expires_atstringNoISO 8601 expiration timestamp. Omit for keys that never expire.
app_idstringNoApp ID. Required when unauthenticated, ignored when authenticated (uses the authenticated app).

Returns

Returns an API Key object and a secret field containing the full key.

Store the secret securely. This is the only time the full API key is returned. Subsequent retrievals only include the key_prefix and key_hint.

curl -X POST https://api.transcodely.com/transcodely.v1.APIKeyService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Production API Key",
    "description": "Used by the video processing pipeline",
    "environment": "live",
    "app_id": "app_k1l2m3n4o5"
  }'
{
  "api_key": {
    "id": "ak_x9y8z7w6v5",
    "name": "Production API Key",
    "description": "Used by the video processing pipeline",
    "key_prefix": "ak_live_",
    "key_hint": "n4o5",
    "environment": "live",
    "scopes": [],
    "created_at": "2025-01-15T10:30:00Z",
    "is_revoked": false
  },
  "secret": "ak_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4"
}

Retrieve an API key

Retrieve an API key by its ID. The secret is never returned after creation.

POST /transcodely.v1.APIKeyService/Get

Parameters

ParameterTypeRequiredDescription
idstringYesAPI key ID (e.g., "ak_x9y8z7w6v5").

Returns

Returns an API Key object (without the secret).

curl -X POST https://api.transcodely.com/transcodely.v1.APIKeyService/Get 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{"id": "ak_x9y8z7w6v5"}'
{
  "api_key": {
    "id": "ak_x9y8z7w6v5",
    "name": "Production API Key",
    "description": "Used by the video processing pipeline",
    "key_prefix": "ak_live_",
    "key_hint": "n4o5",
    "environment": "live",
    "scopes": [],
    "last_used_at": "2025-02-28T14:22:00Z",
    "expires_at": "2026-01-15T10:30:00Z",
    "created_at": "2025-01-15T10:30:00Z",
    "is_revoked": false
  }
}

List API keys

List API keys with optional filtering by environment and revocation status.

POST /transcodely.v1.APIKeyService/List

Parameters

ParameterTypeRequiredDescription
environmentstringNoFilter by environment: "live" or "test".
include_revokedbooleanNoIf true, include revoked keys. Default: false.
paginationobjectNoPagination parameters. See API Reference overview.

Returns

Returns a list of API Key objects and pagination metadata.

curl -X POST https://api.transcodely.com/transcodely.v1.APIKeyService/List 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "environment": "live",
    "include_revoked": false,
    "pagination": {"limit": 20}
  }'
{
  "api_keys": [
    {
      "id": "ak_x9y8z7w6v5",
      "name": "Production API Key",
      "description": "Used by the video processing pipeline",
      "key_prefix": "ak_live_",
      "key_hint": "n4o5",
      "environment": "live",
      "scopes": [],
      "last_used_at": "2025-02-28T14:22:00Z",
      "created_at": "2025-01-15T10:30:00Z",
      "is_revoked": false
    }
  ],
  "pagination": {
    "next_cursor": "",
    "total_count": 1
  }
}

Revoke an API key

Revoke an API key. Revoked keys immediately stop working for authentication and cannot be reactivated.

POST /transcodely.v1.APIKeyService/Revoke

Parameters

ParameterTypeRequiredDescription
idstringYesAPI key ID.
reasonstringNoReason for revocation, stored for audit purposes (max 500 chars).

Returns

Returns the API Key object with is_revoked: true and revoked_at set.

curl -X POST https://api.transcodely.com/transcodely.v1.APIKeyService/Revoke 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "id": "ak_x9y8z7w6v5",
    "reason": "Key compromised, rotating credentials"
  }'
{
  "api_key": {
    "id": "ak_x9y8z7w6v5",
    "name": "Production API Key",
    "description": "Used by the video processing pipeline",
    "key_prefix": "ak_live_",
    "key_hint": "n4o5",
    "environment": "live",
    "scopes": [],
    "created_at": "2025-01-15T10:30:00Z",
    "is_revoked": true,
    "revoked_at": "2025-02-28T15:00:00Z"
  }
}