Authentication

RolesAPI authenticates every request with an API key passed as a Bearer token. Keys are prefixed rk_ and are tied to your account, plan, and rate limit.

curl "https://api.rolesapi.com/v1/me" \
  -H "Authorization: Bearer rk_live_your_key"

Where do I create a key?

In the dashboard, open API keys and click Create key. Give it a name that describes where it will live (production-worker, local-dev). The full secret is shown exactly once, at creation time — after that, only the prefix is visible. If you lose a key, create a new one and revoke the old one; secrets are never redisplayed.

How should I store keys?

• Keep keys in environment variables or a secrets manager, never in source control.
• Use one key per environment or service, so a leak has a small blast radius and revocation does not take down everything at once.
• Never use an rk_ key in browser or mobile code that ships to users. Call RolesAPI from your backend and proxy what the client needs.
• Scrub keys from logs. The Authorization header should never be written to application logs or error trackers.

What does an authentication failure look like?

A missing header returns 401 missing_api_key:

{
  "error": {
    "code": "missing_api_key",
    "message": "No API key provided. Pass it as: Authorization: Bearer rk_...",
    "request_id": "req_2c91d0aa"
  }
}

A revoked, malformed, or unknown key returns 401 invalid_api_key:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "request_id": "req_5b7e13f2"
  }
}

Both are permanent for that key — do not retry with the same credentials. The full code list is in Errors.

How do I rotate a key?

Rotation is a create-then-revoke sequence with zero downtime:

1. Create a new key in the dashboard.
2. Deploy the new key to your services.
3. Confirm traffic on the new key — GET /v1/usage shows which requests each key made.
4. Revoke the old key. Revocation is immediate; in-flight requests already authenticated are unaffected, and any later use returns invalid_api_key.

Rotate on a schedule that matches your security policy, and immediately if you suspect a key has been exposed.