# 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 <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 · 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<date-time> | 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<date-time> | 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<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.

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

- `revokedAt` string<date-time> | 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<date-time> required  
    ISO 8601 timestamp of the last change to the key.

### Example Request
```sh
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
```json
{  
  "$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
```json
{  
  "$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"  
}
```