API Key Management

Overview

The API keys endpoints allow you to create, list, and revoke API keys programmatically. Use them to:

• Automate key rotation.
• Separate keys per service, environment, or team.
• Revoke compromised or unused keys quickly.

Treat these endpoints and the resulting keys as highly sensitive.

Endpoint summary

Common operations include:

The exact path parameters and response structure may vary by deployment, but the patterns below illustrate typical behavior.

Authentication

API key management endpoints require strong authentication and are generally not accessible to regular inference-only keys. They typically accept:

• An admin-scoped API key:
  • Authorization: Bearer <admin-api-key>
• Or a JWT access token with appropriate scopes:
  • Authorization: Bearer <access-token>

See Authentication for details on roles, scopes, and token issuance.

GET /v1/api-keys

List existing API keys for the authenticated account or workspace. For security reasons, the full secret values are not returned—only metadata.

• Method: GET
• Path: /v1/api-keys

Example response

{
  "data": [
    {
      "id": "key_123",
      "name": "production-backend",
      "prefix": "mrk_live_",
      "last_four": "abcd",
      "created_at": "2024-01-01T12:00:00Z",
      "last_used_at": "2024-01-05T09:30:00Z",
      "scopes": ["inference", "config:read"],
      "revoked": false
    },
    {
      "id": "key_456",
      "name": "staging-ci",
      "prefix": "mrk_test_",
      "last_four": "wxyz",
      "created_at": "2024-01-02T10:00:00Z",
      "last_used_at": null,
      "scopes": ["inference"],
      "revoked": false
    }
  ]
}

POST /v1/api-keys

Create a new API key. The response typically returns the full secret value once; you are responsible for storing it securely.

• Method: POST
• Path: /v1/api-keys

Example request (cURL)

curl https://api.multiroute.ai/v1/api-keys \
  -H "Authorization: Bearer $MULTIROUTE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-service-key",
    "scopes": ["inference"],
    "expires_at": "2025-01-01T00:00:00Z"
  }'

Example request body

{
  "name": "new-service-key",
  "scopes": ["inference"],
  "expires_at": "2025-01-01T00:00:00Z"
}

Example response

{
  "id": "key_789",
  "name": "new-service-key",
  "secret": "mrk_live_XXXXXXXXXXXXXXXXXXXXXXXX",
  "created_at": "2024-01-10T08:00:00Z",
  "scopes": ["inference"],
  "expires_at": "2025-01-01T00:00:00Z"
}

Important: The secret value is usually only returned once. Store it securely and never log it in plaintext.

DELETE /v1/api-keys/{key_id}

Revoke (delete) an API key so it can no longer be used to authenticate.

• Method: DELETE
• Path: /v1/api-keys/{key_id}

Example request (cURL)

curl -X DELETE https://api.multiroute.ai/v1/api-keys/key_789 \
  -H "Authorization: Bearer $MULTIROUTE_ADMIN_TOKEN"

Example response

{
  "status": "ok",
  "id": "key_789",
  "revoked": true
}

Security best practices

• Store keys in environment variables or secrets managers: Never hardcode API keys in source code or commit them to version control.
• Use least privilege: Create separate keys with minimal scopes for each service and environment.
• Rotate keys regularly: Automate key rotation and remove unused or stale keys.
• Monitor usage: Track which keys are used where, and quickly revoke those that appear compromised.

For more on secure handling of credentials, see the security documentation (for example, /docs/security/index if available in your deployment).

Related documentation

• Authentication
• Errors & retry guidance