Management

API Keys

Create, list, update, regenerate, and revoke API keys programmatically. Manage your API keys through the dashboard or via these endpoints.

Bearer Token Authentication

These endpoints use Authorization: Bearer header with your JWT from your dashboard login, not the x-api-key header. These are dashboard-level operations for managing your API keys. The API keys themselves are used with x-api-key for render and other API calls.

Endpoints Overview

Method	Endpoint	Description
POST	`/api/v1/api-keys`	Create a new API key
GET	`/api/v1/api-keys`	List all API keys
PATCH	`/api/v1/api-keys/{key_id}`	Update API key name
DELETE	`/api/v1/api-keys/{key_id}`	Revoke an API key
POST	`/api/v1/api-keys/{key_id}/regenerate`	Regenerate an API key

Create API Key

POST/api/v1/api-keys

Generate a new API key. Store the key value securely as soon as you receive it.

Save Your Key Immediately

Store the API key in a secure location right away. The full value is shown only in this creation response and will not be shown again. All other responses return a masked sm_****<last4>.

Headers

AuthorizationstringRequired

Bearer token: a JWT from your dashboard login (e.g., 'Bearer eyJhbGci...')

Content-TypestringRequired

Must be application/json

Request Body

namestringRequired

Descriptive name for the API key (1-255 characters). Examples: 'Production API', 'Development', 'Staging Server'.

expires_in_daysinteger

Number of days until the key expires (1-3650). If omitted or null, the key never expires.

Request Body

1{
2  "name": "Production API",
3  "expires_in_days": 365
4}

Response

201Created

Response 201 Created

1{
2  "id": "123e4567-e89b-12d3-a456-426614174000",
3  "name": "Production API",
4  "key": "sm_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
5  "is_active": true,
6  "last_used_at": null,
7  "created_at": "2026-03-22T10:00:00Z",
8  "updated_at": null,
9  "revoked_at": null,
10  "expires_at": "2027-03-22T10:00:00Z"
11}

Response Fields

idstring (UUID)Required

Unique identifier for the API key. Use this ID for update, delete, and regenerate operations.

namestringRequired

The name you assigned to the key.

keystringRequired

The API key starting with 'sm_'. Full value returned only at creation and regeneration; all other responses return a masked sm_****<last4>.

is_activebooleanRequired

Whether the key is currently active. Always true for newly created keys.

last_used_atstring (ISO 8601) | null

Timestamp of when the key was last used for an API call. Null if never used.

created_atstring (ISO 8601)Required

Timestamp of when the key was created.

updated_atstring (ISO 8601) | null

Timestamp of when the key metadata was last updated (e.g., name change). Null for newly created keys.

revoked_atstring (ISO 8601) | null

Timestamp of when the key was revoked. Null for active keys.

expires_atstring (ISO 8601) | null

Timestamp of when the key expires. Null if the key never expires.

Code Examples

Create API Key

bash

1curl -X POST "https://api.sudomock.com/api/v1/api-keys" \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer YOUR_SUPABASE_JWT" \
4  -d '{
5    "name": "Production API",
6    "expires_in_days": 365
7  }'

Error Responses

401Unauthorized

Returned when the Bearer token is missing, malformed, or invalid. The detail message varies:

json

1// Missing Authorization header entirely
2{ "detail": "Missing Authorization header", "success": false }
3
4// Malformed header (not "Bearer <token>" format)
5{ "detail": "Invalid Authorization header format. Expected: 'Bearer <token>'", "success": false }
6
7// Expired or invalid JWT token
8{ "detail": "Invalid or expired token", "success": false }
9
10// Server-side token validation failure
11{ "detail": "Token validation failed", "success": false }

422Validation Error

json

1{
2  "detail": "Validation error",
3  "errors": [
4    {
5      "field": "body -> name",
6      "message": "Missing required field: body -> name"
7    }
8  ],
9  "success": false
10}

500Internal Server Error

json

1{
2  "detail": "Internal error while creating API key",
3  "success": false
4}

List API Keys

GET/api/v1/api-keys

Retrieve all API keys for the authenticated user. Returns both active and revoked keys, ordered by creation date (newest first). Useful for displaying key management interfaces.

Headers

AuthorizationstringRequired

Bearer token: a JWT from your dashboard login

Response

200OK

Response 200 OK

1{
2  "keys": [
3    {
4      "id": "123e4567-e89b-12d3-a456-426614174000",
5      "name": "Production API",
6      "key": "sm_****a1b2",
7      "is_active": true,
8      "last_used_at": "2026-03-22T14:30:00Z",
9      "created_at": "2026-03-01T08:00:00Z",
10      "updated_at": "2026-03-15T12:00:00Z",
11      "revoked_at": null,
12      "expires_at": "2027-03-01T08:00:00Z"
13    },
14    {
15      "id": "987fcdeb-51a2-43e7-b890-123456789abc",
16      "name": "Development",
17      "key": "sm_****f8e7",
18      "is_active": true,
19      "last_used_at": null,
20      "created_at": "2026-03-20T09:00:00Z",
21      "updated_at": null,
22      "revoked_at": null,
23      "expires_at": null
24    }
25  ],
26  "total": 2
27}

Response Fields

keysarrayRequired

Array of API key objects. Each object contains the same fields as the create response (id, name, key, is_active, last_used_at, created_at, updated_at, revoked_at, expires_at). The key value is masked as sm_****<last4>.

totalintegerRequired

Total number of API keys (includes both active and revoked keys).

Code Examples

List API Keys

bash

1curl -X GET "https://api.sudomock.com/api/v1/api-keys" \
2  -H "Authorization: Bearer YOUR_SUPABASE_JWT"

Error Responses

401Unauthorized

json

1{
2  "detail": "Missing Authorization header",
3  "success": false
4}

Other possible messages: Invalid Authorization header format. Expected: 'Bearer <token>', Invalid or expired token, Token validation failed.

500Internal Server Error

json

1{
2  "detail": "Internal error while listing API keys",
3  "success": false
4}

Update API Key

PATCH/api/v1/api-keys/{key_id}

Update the name of an existing API key. This does not affect the key value itself or its active status.

Headers

AuthorizationstringRequired

Bearer token: a JWT from your dashboard login

Content-TypestringRequired

Must be application/json

Path Parameters

key_idstring (UUID)Required

The UUID of the API key to update (from the create or list response).

Request Body

namestringRequired

New name for the API key (1-255 characters).

Request Body

1{
2  "name": "Production API v2"
3}

Response

200OK

Response 200 OK

1{
2  "id": "123e4567-e89b-12d3-a456-426614174000",
3  "name": "Production API v2",
4  "key": "sm_****a1b2",
5  "is_active": true,
6  "last_used_at": "2026-03-22T14:30:00Z",
7  "created_at": "2026-03-01T08:00:00Z",
8  "updated_at": "2026-03-22T15:00:00Z",
9  "revoked_at": null,
10  "expires_at": "2027-03-01T08:00:00Z"
11}

Code Examples

Update API Key

bash

1curl -X PATCH "https://api.sudomock.com/api/v1/api-keys/123e4567-e89b-12d3-a456-426614174000" \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer YOUR_SUPABASE_JWT" \
4  -d '{
5    "name": "Production API v2"
6  }'

Error Responses

401Unauthorized

json

1{
2  "detail": "Missing Authorization header",
3  "success": false
4}

Other possible messages: Invalid Authorization header format. Expected: 'Bearer <token>', Invalid or expired token, Token validation failed.

422Validation Error

json

1{
2  "detail": "Validation error",
3  "errors": [
4    {
5      "field": "body -> name",
6      "message": "Missing required field: body -> name"
7    }
8  ],
9  "success": false
10}

404Not Found

json

1{
2  "detail": "API key not found",
3  "success": false
4}

500Internal Server Error

json

1{
2  "detail": "Internal error while updating API key",
3  "success": false
4}

Revoke API Key

DELETE/api/v1/api-keys/{key_id}

Revoke (deactivate) an API key. The key will immediately stop working for authentication. This action cannot be undone. The revoked key will still appear in the list response with is_active: false.

Immediate Invalidation

Revoked keys stop working immediately, everywhere. Any in-flight requests using this key will fail. Make sure you have updated all services using this key before revoking.

Headers

AuthorizationstringRequired

Bearer token: a JWT from your dashboard login

Path Parameters

key_idstring (UUID)Required

The UUID of the API key to revoke.

Response

204No Content

Returns no body on success. The HTTP status code 204 confirms the key has been revoked.

Code Examples

Revoke API Key

bash

1curl -X DELETE "https://api.sudomock.com/api/v1/api-keys/123e4567-e89b-12d3-a456-426614174000" \
2  -H "Authorization: Bearer YOUR_SUPABASE_JWT"

Error Responses

401Unauthorized

json

1{
2  "detail": "Missing Authorization header",
3  "success": false
4}

Other possible messages: Invalid Authorization header format. Expected: 'Bearer <token>', Invalid or expired token, Token validation failed.

404Not Found

json

1{
2  "detail": "API key not found",
3  "success": false
4}

500Internal Server Error

json

1{
2  "detail": "Internal error while revoking API key",
3  "success": false
4}

Regenerate API Key

POST/api/v1/api-keys/{key_id}/regenerate

Regenerate an API key. This revokes the old key immediately and creates a new one with the same name. If the original key had an expiration, the new key gets the same duration starting from now. The new key has a new UUID.

Old Key Immediately Revoked

The old key stops working instantly. Save the new key from the response before closing. You will not be able to retrieve it again.

Headers

AuthorizationstringRequired

Bearer token: a JWT from your dashboard login

Path Parameters

key_idstring (UUID)Required

The UUID of the API key to regenerate.

Response

201Created

Response 201 Created

1{
2  "id": "aabbccdd-1122-3344-5566-778899aabbcc",
3  "name": "Production API v2",
4  "key": "sm_9f8e7d6c5b4a3029182736455463728190a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5",
5  "is_active": true,
6  "last_used_at": null,
7  "created_at": "2026-03-22T16:00:00Z",
8  "updated_at": null,
9  "revoked_at": null,
10  "expires_at": "2027-03-22T16:00:00Z"
11}

The response contains the new key with a new UUID. The response fields are identical to the create response. The old key's id is now revoked and no longer usable.

Code Examples

Regenerate API Key

bash

1curl -X POST "https://api.sudomock.com/api/v1/api-keys/123e4567-e89b-12d3-a456-426614174000/regenerate" \
2  -H "Authorization: Bearer YOUR_SUPABASE_JWT"

Error Responses

401Unauthorized

json

1{
2  "detail": "Missing Authorization header",
3  "success": false
4}

Other possible messages: Invalid Authorization header format. Expected: 'Bearer <token>', Invalid or expired token, Token validation failed.

404Not Found

json

1{
2  "detail": "API key not found",
3  "success": false
4}

500Internal Server Error

json

1{
2  "detail": "Internal error while regenerating API key",
3  "success": false
4}

Key Format

All SudoMock API keys follow a consistent format:

API Key Format

1sm_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
2|  |                                                                |
3|  +--- 64 hex characters (32 random bytes) ------------------------+
4|
5sm_ prefix (identifies SudoMock keys)

Component	Value	Description
Prefix	`sm_`	Identifies the key as a SudoMock API key
Random part	64 hex characters	Cryptographically random, generated from 32 bytes
Total length	67 characters	Prefix (3) + random (64)

Best Practices

Use separate keys per environment

Create distinct keys for production, staging, and development. This lets you rotate or revoke keys without affecting other environments.

Store keys in environment variables

Never hardcode API keys in source code. Use .env files, secret managers, or your platform's environment variable configuration.

Set expiration dates

Use expires_in_days to automatically expire keys. This reduces risk if a key is compromised. 365 days is a good default for production keys.

Rotate keys regularly

Use the regenerate endpoint for zero-downtime key rotation. Create the new key, update your services, and the old key is automatically revoked.

Use descriptive names

Name your keys clearly (e.g., "Production Server", "n8n Automation", "Shopify Integration") to easily identify which key is used where.

Key Rotation Workflow

For zero-downtime rotation: call the regenerate endpoint, update your services with the new key from the response, and the old key is immediately invalidated. No need to separately revoke.

Authentication Render Mockup