API Keys

API keys authenticate all requests to the Mandato API. Each key is scoped to an account and an environment (test or production). You can create multiple keys for different services, CI/CD pipelines, or team members.

API key object

When listing keys, the key value is masked — only the prefix is shown.

{
  "id": "key_a1b2c3d4e5f6",
  "name": "Production backend",
  "keyPrefix": "sk_live_4f8a",
  "environment": "production",
  "lastUsedAt": "2025-01-15T10:00:00.000Z",
  "expiresAt": null,
  "revokedAt": null,
  "createdAt": "2025-01-10T09:00:00.000Z"
}

Fields

Field	Type	Description
id	string	Unique API key identifier
name	string	Human-readable name for the key
keyPrefix	string	First 12 characters of the key (e.g., sk_live_4f8a)
environment	string	test or production
lastUsedAt	string|null	ISO 8601 timestamp of last use
expiresAt	string|null	ISO 8601 expiration timestamp (null = never expires)
revokedAt	string|null	ISO 8601 revocation timestamp (null = active)
createdAt	string	ISO 8601 creation timestamp

API key creation response

When creating a key, the full key value is returned once:

{
  "id": "key_a1b2c3d4e5f6",
  "key": "sk_live_4f8a9b2c3d1e6f7a8b9c0d1e2f3a4b5c",
  "keyPrefix": "sk_live_4f8a",
  "name": "Production backend",
  "environment": "production",
  "expiresAt": null,
  "createdAt": "2025-01-10T09:00:00.000Z"
}

Caution

The full key value is only returned once, at creation time. Store it immediately in a secure location (environment variable, secrets manager, etc.). You cannot retrieve the full key again.

---

List API keys

GET /v1/api-keys

Returns all API keys for your account, including revoked keys. Key values are masked.

Example request

curl https://api.getmandato.dev/v1/api-keys \
  -H "Authorization: Bearer sk_test_your_key"

Example response

{
  "data": [
    {
      "id": "key_a1b2c3d4e5f6",
      "name": "Production backend",
      "keyPrefix": "sk_live_4f8a",
      "environment": "production",
      "lastUsedAt": "2025-01-15T10:00:00.000Z",
      "expiresAt": null,
      "revokedAt": null,
      "createdAt": "2025-01-10T09:00:00.000Z"
    },
    {
      "id": "key_f6e5d4c3b2a1",
      "name": "CI/CD pipeline",
      "keyPrefix": "sk_test_b2c1",
      "environment": "test",
      "lastUsedAt": "2025-01-14T16:30:00.000Z",
      "expiresAt": "2026-01-01T00:00:00.000Z",
      "revokedAt": null,
      "createdAt": "2025-01-11T10:00:00.000Z"
    },
    {
      "id": "key_c3d4e5f6a1b2",
      "name": "Old staging key",
      "keyPrefix": "sk_test_9a8b",
      "environment": "test",
      "lastUsedAt": "2024-12-01T08:00:00.000Z",
      "expiresAt": null,
      "revokedAt": "2025-01-05T12:00:00.000Z",
      "createdAt": "2024-06-15T09:00:00.000Z"
    }
  ]
}

---

Create an API key

POST /v1/api-keys

Creates a new API key. The full key value is included in the response and will not be shown again.

Request body

Field	Type	Required	Description
name	string	Yes	Descriptive name for the key
environment	string	No	test (default) or production
expiresAt	string	No	ISO 8601 expiration date. Omit for a key that never expires.

Example request

curl -X POST https://api.getmandato.dev/v1/api-keys \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production backend",
    "environment": "production",
    "expiresAt": "2026-01-01T00:00:00.000Z"
  }'

Example response (201 Created)

{
  "data": {
    "id": "key_a1b2c3d4e5f6",
    "key": "sk_live_4f8a9b2c3d1e6f7a8b9c0d1e2f3a4b5c",
    "keyPrefix": "sk_live_4f8a",
    "name": "Production backend",
    "environment": "production",
    "expiresAt": "2026-01-01T00:00:00.000Z",
    "createdAt": "2025-01-10T09:00:00.000Z"
  }
}

Error responses

Status	Type	Description
400	validation_error	Missing name, invalid environment, or invalid expiration date

---

Revoke an API key

DELETE /v1/api-keys/:id

Revokes an API key immediately. Revoked keys cannot be used to authenticate and cannot be re-activated. Create a new key as a replacement.

Path parameters

Parameter	Type	Description
id	string	API key ID (e.g., key_a1b2c3d4e5f6)

Example request

curl -X DELETE https://api.getmandato.dev/v1/api-keys/key_a1b2c3d4e5f6 \
  -H "Authorization: Bearer sk_test_your_key"

Example response

{
  "data": {
    "id": "key_a1b2c3d4e5f6",
    "revoked": true
  }
}

Error responses

Status	Type	Description
404	not_found	API key not found or belongs to a different account
409	conflict	API key is already revoked

Note

You cannot revoke the API key you are currently using to authenticate the request. Use a different key or the dashboard to revoke it.

---

Key naming conventions

Use descriptive names that indicate the purpose and environment of each key:

Name	Environment	Usage
Production backend	production	Main application server
CI/CD pipeline	test	Automated testing in CI
Staging server	test	Pre-production environment
Mobile app v2	production	Mobile client integration
Partner integration - Acme	production	Third-party partner access

This makes it easy to identify which key to revoke if one is compromised, and to audit key usage in the dashboard.