Authentication

Every credential the Spacefast API accepts, where each one is created, what it can reach, and which routes refuse it.

The API takes one header. After this page, you know which credential to mint for your case, how to scope it, and why a valid token still gets a 403 on some routes.

The header

Authorization: Bearer <token>

The scheme match is case-sensitive, so bearer is not accepted. A DPoP scheme is also read, and always routes to the session and OAuth verifier.

The server decides what a token is from its prefix before any verifier runs.

Partner JWTs have no Spacefast prefix. The API recognizes their signed at+jwt profile. See Partner API for issuer activation and customer scope.

API keys

An sfa_ key is 56 characters of [0-9A-Za-z] after the prefix. It is the credential for the CLI, CI, and server-to-server calls.

Create one with a scope and a permission list:

curl -sS -X POST https://api.spacefast.com/v1/api-keys \
  -H "Authorization: Bearer $SPACEFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "CI publish",
        "scope": { "kind": "team", "teamId": "team_example" },
        "permissions": ["spaces:publish", "versions:promote", "teams:read"],
        "expiresAt": "2027-01-01T00:00:00.000Z"
      }'

const created = await client.post("/v1/api-keys", {
  body: {
    name: "CI publish",
    scope: { kind: "team", teamId: "team_example" },
    permissions: ["spaces:publish", "versions:promote", "teams:read"],
    expiresAt: "2027-01-01T00:00:00.000Z",
  },
});

Three rules the code enforces:

• The secret appears once.POST /v1/api-keys is the only response carrying secret. Every other API-key response carries secretPreview (first 8 characters, then the last 4).
• A key can never exceed its creator. The derived policy must be a subset of the calling credential’s policy. A wider request fails with policy_exceeds_grantor.
• Secrets are immutable. There is no rotate-in-place. Create a new key, move traffic, then revoke the old one with DELETE /v1/api-keys/{apiKeyId}. That returns 204 and keeps the record for audit.

PATCH /v1/api-keys/{apiKeyId} changes name, scope, permissions, allowlist, and expiry. scope and permissions must be sent together or both omitted.

In the dashboard, keys live on the team’s Agents page under API keys. The create form asks for Name, a Policy preset, and an optional Expires, then shows the secret once behind Copy this key now. It won’t be shown again.

The presets and what they grant:

An API key carries its own request budget of 50,000 requests per rolling hour, on top of the general rate limits.

Space keys

An anonymous POST /v1/publish (no credential at all) creates an unclaimed Space and returns a claim block holding an sfc_ Space key. That key is also the fragment of the claim URL and the token of the Space’s /__/<key> door.

A Space key reaches only its own Space, and only the operations an unclaimed Space must still support: read the Space, open a new version, refresh uploads, finalize, promote, list activity, mint share links, restore after a delete. Operations declaring bearerAuth alone refuse it.

Unclaimed Spaces expire. The default window is 33 hours and 20 minutes from creation or the latest publish that changes files, capped at 30 days from creation. Reading the Space with its key, which is what the claim page does, moves the deadline to one hour out when less than an hour remains, up to 6 hours of extension in total. Claim it with POST /v1/claim to remove the deadline, or exchange the key for an API key with POST /v1/claim/exchange.

Space machine credentials

An sfm_ credential is sfm_ plus a 32-character opaque token, minted for one Space so a machine can reach it without a team-wide key. POST /v1/spaces/{spaceId}/machine-credentials takes a name, the resources and capabilities the credential may use, and a target, then returns { credential, token }.

The token is returned exactly once, on create and on rotate, and it is accepted only in the Authorization header. Afterwards listings show a hint of the form sfm_…<last 4>. Rotate with POST .../machine-credentials/{credentialId}/rotate, which invalidates the previous token and keeps the grant. Revoke with DELETE .../machine-credentials/{credentialId}.

Creating, rotating, and revoking a machine credential all need an API key or a session. A machine credential cannot mint another one.

Sessions and OAuth

A signed-in browser session works as a cookie and as Authorization: Bearer <session token>. A session has no stored policy. It compiles one per team from the caller’s live role, so an owner or admin gets everything the team can do and a member gets read, create, write, rename, publish, promote, download, and build actions.

For third-party apps, Spacefast is an OAuth 2.0 authorization server.

Authorization code is the flow for people, client credentials for machines. The scopes:

spaces:publish and builds:trigger exist only on the API resource. Their actions are already covered by publish:write.

A token that authenticates but lacks a scope set the operation accepts fails with insufficient_scope.

Device login for CLIs and agents

A headless client starts at POST /v1/auth/device, shows the user the verification code, then polls POST /v1/auth/device/poll until the user approves. Approval and denial run through POST /v1/auth/device/approve and /deny, which need a signed-in browser session. While the user has not decided yet, the poll answers authorization_pending. That is a wait, not a failure.

The code lifetime, the poll cadence, and what the approved credential is good for are on Sign in and security.

Which routes refuse which credential

Three refusals are worth knowing before you debug one.

Person-only operations. An operation whose only declared scheme is the session cookie needs a human behind the request. Account email changes, adding a password, approving a device authorization, approving or denying an agent action, and listing repository installations all refuse an API key or a machine credential. The same session token still works as a bearer token, so this is about the credential kind, not the transport.

Team-scoped reads. A Space key reaches its own Space, not the team around it. Listing versions, listing a team’s spaces, reading API keys, and managing webhooks all declare bearerAuth alone and refuse it.

Anonymous publish.POST /v1/publish is the one operation that accepts no credential at all. It creates an unclaimed Space and returns a claim block. Retrying it with an Idempotency-Key needs a self-supplied replay principal, because there is no credential to scope the key by. See Idempotency.

Failures