API keys: create, list, revoke, and update

The API Keys endpoints let you manage programmatic access tokens for the Shipfastai API. API keys can be used as an alternative to JWT Bearer tokens for authenticating requests to AI and RAG endpoints. All key management operations require JWT authentication — you cannot use an API key to manage other API keys.

API key management is available on Pro and Enterprise plans only. All endpoints are mounted under /api/api-keys/.

POST /api/api-keys

Create a new API key. The plaintext key is returned only once in the response. Store it securely — it cannot be retrieved again after creation. Headers:

string

required

Bearer <access_token> — JWT authentication only.

Request body:

string

required

A descriptive name for the API key (e.g., "Production server", "CI pipeline").

string

Optional ISO 8601 expiration timestamp. If omitted, the key does not expire.

curl --request POST \
  --url http://localhost:8000/api/api-keys \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Production server",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

import requests

response = requests.post(
    "http://localhost:8000/api/api-keys",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "name": "Production server",
        "expires_at": "2027-01-01T00:00:00Z",
    },
)
data = response.json()
print(f"Save this key: {data['key']}")

Response (201 Created) — ApiKeyCreated:

string

required

UUID of the API key.

string

required

The name you assigned to the key.

string

required

The first 12 characters of the key, used for identification in listings.

string

required

The full plaintext API key. This is the only time the full key is returned. Store it securely.

boolean

required

Whether the key is active. true on creation.

string

required

ISO 8601 timestamp of when the key was created.

string

ISO 8601 timestamp of last usage. null for a newly created key.

string

ISO 8601 expiration timestamp, or null if the key does not expire.

{
  "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "name": "Production server",
  "key_prefix": "sk_a1b2c3d4e5",
  "key": "sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "is_active": true,
  "created_at": "2026-04-09T14:30:00Z",
  "last_used_at": null,
  "expires_at": "2027-01-01T00:00:00Z"
}

GET /api/api-keys

List all API keys for the authenticated user, ordered by creation date (newest first). The full key value is never included — only the prefix is shown for identification. Headers:

string

required

Bearer <access_token> — JWT authentication only.

curl --request GET \
  --url http://localhost:8000/api/api-keys \
  --header "Authorization: Bearer <access_token>"

Response — array of ApiKeyResponse:

string

required

UUID of the API key.

string

required

The name assigned to the key.

string

required

The first 12 characters of the key.

boolean

required

Whether the key is active. Revoked keys have is_active: false.

string

required

ISO 8601 creation timestamp.

string

ISO 8601 timestamp of last usage, or null.

string

ISO 8601 expiration timestamp, or null.

[
  {
    "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "name": "Production server",
    "key_prefix": "sk_a1b2c3d4e5",
    "is_active": true,
    "created_at": "2026-04-09T14:30:00Z",
    "last_used_at": "2026-04-09T15:00:00Z",
    "expires_at": "2027-01-01T00:00:00Z"
  }
]

DELETE /api/api-keys/

Revoke an API key. This is a soft delete — the key is marked as inactive and can no longer be used for authentication. The key record is retained for audit purposes. Path parameters:

string

required

The UUID of the API key to revoke.

Headers:

string

required

Bearer <access_token> — JWT authentication only.

curl --request DELETE \
  --url http://localhost:8000/api/api-keys/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d \
  --header "Authorization: Bearer <access_token>"

Response:

{
  "message": "API key revoked"
}

Returns 404 if the key does not exist or does not belong to the authenticated user.

PATCH /api/api-keys/

Update an API key’s display name. Path parameters:

string

required

The UUID of the API key to update.

Headers:

string

required

Bearer <access_token> — JWT authentication only.

Query parameters:

string

required

The new name for the API key.

curl --request PATCH \
  --url "http://localhost:8000/api/api-keys/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d?name=Staging%20server" \
  --header "Authorization: Bearer <access_token>"

Response — ApiKeyResponse with updated fields:

{
  "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "name": "Staging server",
  "key_prefix": "sk_a1b2c3d4e5",
  "is_active": true,
  "created_at": "2026-04-09T14:30:00Z",
  "last_used_at": "2026-04-09T15:00:00Z",
  "expires_at": "2027-01-01T00:00:00Z"
}

Returns 404 if the key does not exist or does not belong to the authenticated user.

Using API keys for authentication

Once you have a key, pass it in the Authorization header as a Bearer token, the same way you pass a JWT:

Authorization: Bearer sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

API keys are accepted on AI and RAG endpoints alongside JWTs. The backend automatically detects whether the token is a JWT or an API key.

Overview

Endpoints

API keys: create, list, revoke, and update

POST /api/api-keys

GET /api/api-keys

DELETE /api/api-keys/

PATCH /api/api-keys/

Using API keys for authentication

​POST /api/api-keys

​GET /api/api-keys

​DELETE /api/api-keys/

​PATCH /api/api-keys/

​Using API keys for authentication

POST /api/api-keys

GET /api/api-keys

DELETE /api/api-keys/

PATCH /api/api-keys/

Using API keys for authentication