Docs/API Keys

API Keys

API keys are scoped to a project and control access to the upload API. Each key can be restricted to specific destinations.

Key Format

API keys use the aptr_ prefix followed by a random string. Keys are only shown in full once at creation time.

aptr_{env}_{random}

Important

The plain-text key is only returned when the key is created. Store it securely — it cannot be retrieved again.

List Keys

GET/api/v1/projects/:projectId/keys

Retrieve all API keys for a project.

curl https://api.apertur.ca/api/v1/projects/proj_.../keys \
  -H "Authorization: Bearer aptr_live_xxxx"

Create a Key

POST/api/v1/projects/:projectId/keys

Generate a new API key for a project.

Field	Type	Description
label	string	Human-readable label for the key
maxImages	integer	Maximum number of images allowed per session (optional)
expiresAt	string \| null	ISO 8601 timestamp after which the key stops working, or null for a key that never expires (optional)

curl -X POST https://api.apertur.ca/api/v1/projects/proj_.../keys \
  -H "Authorization: Bearer aptr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Production",
    "maxImages": 100
  }'

# Response includes plainTextKey — save it, it is only shown once!
# { "key": { "id": "key_..." }, "plainTextKey": "aptr_live_z9y8x7..." }

Assign Destinations

PUT/api/v1/keys/:keyId/destinations

Bind specific destinations to a key. Sessions created with this key will deliver images only to these destinations. Optionally enable long polling.

curl -X PUT https://api.apertur.ca/api/v1/keys/key_.../destinations \
  -H "Authorization: Bearer aptr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_ids": ["dest_abc", "dest_def"],
    "long_polling": true
  }'

Request Signing

Turn HMAC request signing on or off for a key, or rotate its secret. See Request signing for the full header and signature format.

Enable

POST/api/v1/projects/:projectId/keys/:keyId/signing/enable

Enable signing on a key and generate its signing secret.

curl -X POST https://api.aptr.ca/api/v1/projects/proj_.../keys/key_.../signing/enable \
  -H "Authorization: Bearer aptr_live_xxxx"

# Response — save the secret, it is only shown once!
# { "signingSecret": "b7e2c1f4a9..." }

Rotate

POST/api/v1/projects/:projectId/keys/:keyId/signing/rotate

Replace a key's signing secret. The previous secret stops working immediately.

curl -X POST https://api.aptr.ca/api/v1/projects/proj_.../keys/key_.../signing/rotate \
  -H "Authorization: Bearer aptr_live_xxxx"

# Response — the previous secret stops working immediately.
# { "signingSecret": "9f1a3d0e77..." }

Disable

POST/api/v1/projects/:projectId/keys/:keyId/signing/disable

Turn off signing for a key. Requests no longer need a signature.

curl -X POST https://api.aptr.ca/api/v1/projects/proj_.../keys/key_.../signing/disable \
  -H "Authorization: Bearer aptr_live_xxxx"

# { "ok": true }

← Destinations Next: Webhooks →