API Keys

CTFFactory's REST API uses API keys for programmatic authentication. Keys are long-lived tokens scoped to specific capabilities, making it straightforward to grant the minimum necessary access to automated pipelines, integrations, and third-party tools.

Key Format

All CTFFactory API keys begin with the prefix ctff_ followed by a random alphanumeric string. Example:

ctff_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Treat your API key like a password. Do not commit it to version control or expose it in client-side code.

Creating an API Key

1. Navigate to Account Settings > API Keys (for personal keys) or Workspace Settings > API Keys (for workspace-scoped keys visible to Admins and Owners).
2. Click Create API Key.
3. Enter a descriptive name for the key (e.g., CI/CD Pipeline, Slack Integration).
4. Select one or more scopes (see the Scopes table below).
5. Optionally set an expiry date. Keys without an expiry are valid indefinitely until revoked.
6. Click Generate Key.

Important: The full key value is shown only once, immediately after creation. Copy it and store it securely (e.g., in a secrets manager or CI/CD environment variable). CTFFactory stores only a hash of the key and cannot display it again.

Scopes

Each API key is granted one or more scopes that define which operations it may perform. Request only the scopes your integration actually needs.

Scopes are additive — a key with ctf:read and ctf:write can read and write but cannot deploy or perform admin actions.

Principle of least privilege: For read-only dashboards or reporting integrations, issue keys with only ctf:read. For CI/CD pipelines that deploy CTFs, use ctf:write and ctf:deploy without ctf:admin.

Authenticating with an API Key

Include the key in the Authorization header of every API request using the Bearer token scheme:

GET /api/v1/ctfs HTTP/1.1
Host: app.ctffactory.io
Authorization: Bearer ctff_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Content-Type: application/json

Example using curl:

curl -s https://app.ctffactory.io/api/v1/ctfs \
  -H "Authorization: Bearer ctff_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Example using Python requests:

import requests

API_KEY = "ctff_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

response = requests.get(
    "https://app.ctffactory.io/api/v1/ctfs",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
response.raise_for_status()
print(response.json())

Revoking an API Key

To revoke a key immediately:

1. Navigate to Account Settings > API Keys or Workspace Settings > API Keys.
2. Find the key by name.
3. Click Revoke and confirm.

Revocation is instantaneous. Any in-flight requests using the revoked key will receive a 401 Unauthorized response. Revoked keys cannot be restored — generate a new key if continued access is needed.

Workspace Owners can revoke any key in the workspace. Admins and Members can revoke only their own keys.

Key Rotation Best Practice

For production integrations, rotate API keys on a regular schedule (monthly or quarterly) or immediately following any suspected exposure:

1. Generate a new key with the same scopes.
2. Update your secrets manager or CI/CD environment variables with the new key.
3. Verify your integration is functioning correctly with the new key.
4. Revoke the old key.

Setting an expiry date on keys enforces rotation as a hard deadline rather than a soft recommendation.