Create an API key - Spacefast Docs

Create an API key

Creates an API key whose policy grants exactly permissions on exactly scope, and returns it with the full secret. That secret appears in this response only and cannot be read back, so store it before moving on. The request fails with policy_exceeds_grantor when the derived policy reaches past what the calling credential itself holds. A browser session must have reverified recently; an API key caller does not.

POST `/v1/api-keys`

Authorization

Authorization Bearer token · header required

`Authorization: Bearer ` with an API key (`sfa_` prefix), an OAuth access token, a session token, or a Space machine credential (`sfm_` prefix).

Authorization OAuth2 access token · header required

OAuth 2.0 with Spacefast scopes. People use the authorization code flow; machines use client credentials.

Scopes: `teams:create`

Request body

required application/json

expiresAt string | any
ISO 8601 timestamp from which the key stops authenticating. Omit for a key that never expires.
ipAllowlist string[] | any
Exact IP addresses and IPv4 CIDR ranges the key may be used from. Omit to allow any address.
metadata object
Arbitrary metadata to store with the key and return on reads.
name string
Name for the key, shown in the dashboard and in audit events.
notBefore string | any
ISO 8601 timestamp before which the key is rejected. Omit to make it usable immediately.
permissions string[] required
Actions the key may perform on scope. It gets these and nothing beyond them.
scope object required
What the derived policy targets: a team, that team's partner collection, or one Space. A space scope reaches exactly that Space and nothing else the team owns.

Responses

201 Response for status 201

$schema string
Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.
data object required
- collection string required
  team for a key acting on the owning team's own resources, partner for a key acting on customer resources that team manages.
createdAt string required
ISO 8601 timestamp when the key was created.
createdByUserId string required
User account that created the key.
enabled boolean required
False once the key is revoked, which stops it authenticating.
expiresAt string | any required
ISO 8601 timestamp from which requests presenting the key are rejected. Null when it does not expire.
id string required
API key ID (`key_` prefix).
ipAllowlist string[] | any required
Exact IP addresses and IPv4 CIDR ranges the key may be used from. Null when any address is allowed.
lastRequestAt string | any required
ISO 8601 timestamp of the most recent request made with the key. Null until it is used.
metadata object required
Metadata stored with the key when it was created or last updated.
name string | any required
Name given to the key. Null when it was created without one.
notBefore string | any required
ISO 8601 timestamp before which requests presenting the key are rejected. Null when it works from creation.
ownerPrincipal object | any required
Principal that owns the key. Ownership only: what the key may do comes from policy. Null on platform-owned keys.
policy object | any required
Policy the key authorizes by. Null on a device login key, whose authority is recompiled from the holder's live team roles on every request.
revokedAt string | any required
ISO 8601 timestamp when the key was revoked. Null while it is still usable.
secret string required
The key's secret in full, sfa_ followed by 56 characters. Returned in this response only and never readable again.
secretPreview string required
Masked form of the secret: its first eight characters and its last four, joined by three dots.
subject object | any required
What the key acts as in audit records.
teamScope object | any required
Teams a device login key follows the holder's membership in. Null on a key that authorizes by a fixed policy.
updatedAt string required
ISO 8601 timestamp of the last change to the key.

Example Request

curl -X POST "https://api.spacefast.com/v1/api-keys" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{\n  "expiresAt": "2019-08-24T14:15:22Z",\n  "ipAllowlist": [\n    "string"\n  ],\n  "metadata": {\n    "property1": null,\n    "property2": null\n  },\n  "name": "string",\n  "notBefore": "2019-08-24T14:15:22Z",\n  "permissions": [\n    "spaces:read"\n  ],\n  "scope": {\n    "kind": "team",\n    "teamId": "string"\n  }\n}'

Example Response

{  
  "$schema": "http://example.com",  
  "data": {  
    "collection": "team",  
    "createdAt": "2019-08-24T14:15:22Z",  
    "createdByUserId": "string",  
    "enabled": true,  
    "expiresAt": "2019-08-24T14:15:22Z",  
    "id": "string",  
    "ipAllowlist": [\ "string\ "],  
    "lastRequestAt": "2019-08-24T14:15:22Z",  
    "metadata": {  
      "property1": null,  
      "property2": null  
    },  
    "name": "string",  
    "notBefore": "2019-08-24T14:15:22Z",  
    "ownerPrincipal": {  
      "type": "team",  
      "id": "string"  
    },  
    "policy": {  
      "statements": [  
        {  
          "actions": [  
            "spaces:read"  
          ],  
          "conditions": {  
            "request.client": "dashboard"  
          },  
          "effect": "allow",  
          "resources": [  
            "string"  
          ]  
        }  
      ],  
      "version": "2026-06-09"  
    },  
    "preset": "ci_deploy",  
    "revokedAt": "2019-08-24T14:15:22Z",  
    "secret": "string",  
    "secretPreview": "string",  
    "subject": {  
      "type": "user",  
      "id": "string"  
    },  
    "teamScope": {},  
    "updatedAt": "2019-08-24T14:15:22Z"  
  }  
}

Error Response Example

{  
  "$schema": "http://example.com",  
  "type": "string",  
  "title": "string",  
  "status": -9007199254740991,  
  "detail": "string",  
  "code": "string",  
  "pointer": "string",  
  "details": {  
    "property1": null,  
    "property2": null  
  },  
  "suggestions": [  
    "string"  
  ],  
  "next": [  
    "string"  
  ],  
  "requestId": "string"  
}