API keys

Create and manage API keys to authenticate requests to the Matchii API.

Overview

Every request to the Matchii API requires an API key passed in the Authorization header. Keys are scoped to a specific organization and can have fine-grained permissions.

Creating an API key

Navigate to Settings → API Keys in your Matchii dashboard, or use the API:

curl -X POST https://api.matchii.ai/v1/api-keys \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production key",
    "scopes": ["briefs:read", "briefs:write", "matches:read"]
  }'

The response includes the full key — store it immediately, as it won't be shown again:

{
  "id": "key_2f8a3b1c",
  "name": "Production key",
  "key": "mk_live_a1b2c3d4e5f6...",
  "scopes": ["briefs:read", "briefs:write", "matches:read"],
  "created_at": "2026-03-18T10:30:00Z"
}

Key scopes

Scopes control what the key can access. Follow the principle of least privilege.

Using the key

Pass the key as a Bearer token in the Authorization header:

curl https://api.matchii.ai/v1/briefs \
  -H "Authorization: Bearer mk_live_a1b2c3d4e5f6..."

Key rotation

Rotate keys regularly. When you rotate, both old and new keys work for a 24-hour grace period, then the old key is revoked.

curl -X POST https://api.matchii.ai/v1/api-keys/key_2f8a3b1c/rotate \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

Rate limits

Each key is rate-limited based on your plan. See Rate limits & quotas for details.