# 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<date-time>** | **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<date-time>** | **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<uri>**  
  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<date-time>** 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<date-time>** | **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<date-time>** | **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<date-time>** | **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<date-time>** | **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<date-time>** required  
    ISO 8601 timestamp of the last change to the key.