Update an API key

Updates the key’s name, metadata, activation and expiry instants, IP allowlist, or its scope and permissions, and returns the updated key. scope and permissions change together, and must stay on the key’s existing owning team and collection. A key cannot change its own permissions, validity window, or IP allowlist, and a key minted by device login cannot change any of them. Secrets are fixed at creation; create a new key instead.

PATCH /v1/api-keys/{apiKeyId}

Authorization

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

• or -
  Authorization: OAuth2 access token
  OAuth 2.0 with Spacefast scopes. People use the authorization code flow; machines use client credentials.

Scopes: teams:create

Path parameters

• apiKeyId string required
  min length 1

Request body

required application/json

• expiresAt string | any
  Expiry to set, as an ISO 8601 timestamp. Null makes the key never expire.

• ipAllowlist string[] | any
  Replaces the addresses the key may be used from. Null allows any address.

• metadata object
  Replaces the metadata stored with the key.

• name string | any
  Name to set on the key. Null clears it.

• notBefore string | any
  Activation instant to set, as an ISO 8601 timestamp. Null makes the key usable immediately.

• permissions string[]
  Action set to replace the key's permissions with. Send it together with scope. min items 1 · max items 64

• scope object
  Target to recompile the key's policy against. Send it together with permissions, and it must resolve to the key's existing owning team and collection.

Responses

200 Response for status 200

• $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. Allowed: team partner

• 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.

• preset string | any required
  Named permission bundle the key is labeled with. Null when it was created from an explicit policy or permission list.

• revokedAt string | any required
  ISO 8601 timestamp when the key was revoked. Null while it is still usable.

• 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.