API Keys

API keys allow automated systems to interact with Forgecroft. Every key has three dimensions of control: where it can act, what it can do, and which capabilities it holds.

Creating an API Key

For interactive use, forgecroft login handles key creation automatically (see CLI Reference).

To create a key programmatically, use POST /api-keys:

{
  "name": "CI/CD Pipeline",
  "scope_type": "project",
  "scope_id": "project-uuid",
  "action_scope": "write"
}

Important: The raw key value (fc_live_...) is returned only once at creation time. After that, only a masked version (****xxxx) is available. Store it securely.

Scope Type

Controls which resources the key can access:

When creating a project- or workspace-scoped key, you must provide the scope_id (UUID of the resource).

Action Scope

Controls the level of access:

Capability Scopes

Fine-grained permissions that control access to specific API capabilities:

If no capability scopes are specified, the key is a legacy key with full access to all capabilities. Scoped keys must explicitly list each capability.

Verb Scopes

API keys can also have verb-based scopes that control which run operations they can perform:

Verb scopes are specified in the scopes array alongside capability scopes:

{
  "name": "CI Pipeline",
  "scope_type": "project",
  "scope_id": "project-uuid",
  "action_scope": "write",
  "scopes": ["trigger", "read"]
}

This key can trigger plans and read results, but cannot approve runs, apply changes, or manage workspace settings.

Recommended scopes by use case

How Scopes Interact

When an API key has both an action scope and capability/verb scopes, both must be satisfied for a request to succeed. For example:

• A key with action_scope: "admin" and scopes: ["api_keys:read"] can only read API keys — the capability scopes restrict it despite the admin action scope.
• A key with action_scope: "read" and scopes: ["trigger"] cannot trigger runs because the action scope blocks write operations.

If scopes is empty (legacy key), only the action scope is checked.

Anti-Escalation

API keys cannot create child keys with more permissions than they hold:

• A scoped key can only create child keys whose capability scopes are a subset of its own
• A legacy key (empty scopes) can create any type of child key
• A scoped key can never create a legacy (empty-scope) key — even if it holds broad scopes, it cannot escalate to unrestricted access

Key Lifecycle

1. Create — POST /api-keys, store the raw key value
2. Use — Pass as Authorization: Bearer fc_live_...
3. Suspend — PATCH /api-keys/{id} with {"suspended": true} to temporarily disable
4. Resume — PATCH /api-keys/{id} with {"suspended": false}
5. Delete — DELETE /api-keys/{id} to permanently revoke

Suspended keys are immediately rejected with a clear error. Suspension is reversible — use it for temporary disabling without losing the key.

Expired keys are silently rejected (same error as an invalid key). Expiration is checked at request time, not proactively.

Auditing Key Usage

Every API key tracks last_used_at — the timestamp of the last successful request. Use this to identify stale keys:

GET /api-keys

Review keys where last_used_at is null or older than 90 days. Consider suspending keys that are no longer in active use.

Only admins or the key creator can view a specific key’s full metadata via GET /api-keys/{id}.

Incident Response: Leaked Key

If a key is compromised:

1. Suspend immediately — PATCH /api-keys/{id} with {"suspended": true}. This blocks the key within seconds without permanent deletion.
2. Audit usage — Check last_used_at and review recent run activity filtered to the affected workspaces.
3. Create a replacement — Issue a new key with the same scopes.
4. Delete the leaked key — Once you’ve confirmed the replacement is deployed, permanently delete the old key.

Suspend first, investigate second. Suspension is instant and reversible; deletion is permanent.

Key Rotation

To rotate a key without downtime:

1. Create a new key with the same scopes
2. Deploy the new key to your clients
3. Monitor last_used_at on the old key until it stops being used
4. Delete the old key

Principal Types

API keys can be attributed to different principals for audit trail purposes:

Non-admin callers can only create user-principal keys for themselves. Admins can create keys for any principal type and any user.

Choose org for shared automation (the key outlives any individual). Choose user when audit trail attribution matters. Choose team for team-scoped tooling.

Expiration

Keys can be set to expire with expires_in_days. If not specified, the key never expires.

Expired keys fail silently with an “invalid api key” error (identical to a revoked key). Track expires_at in your key inventory and rotate before expiry.

Related API Endpoints

• POST /api-keys — Create an API key
• GET /api-keys — List all API keys for the org (requires api_keys:read capability)
• GET /api-keys/{id} — Get a single key’s metadata (admin or key creator only)
• PATCH /api-keys/{id} — Suspend or unsuspend a key (requires api_keys:write capability)
• DELETE /api-keys/{id} — Revoke a key (requires api_keys:write capability)
• GET /whoami — Verify which key is currently authenticated