Authentication

Sending a token

API tokens are HS256-signed JWTs. Include one in the Authorization header on every request:

curl https://api.onlucra.com/v1/programs \
  -H "Authorization: Bearer $LUCRA_API_TOKEN"

Tokens carry a subject, an actor type, an audience bound to the resource they're minted for (https://api.onlucra.com/v1 for the REST API, https://api.onlucra.com/mcp for MCP), an expiry, and the scopes they grant.

Actors

Every token belongs to one actor type:

• partner — agencies acting on behalf of client brands
• brand — a brand workspace
• creator — an individual creator
• mcp — machine clients using the MCP interface

The current principal

To inspect what a token is bound to — its actor, organization, and scopes — use POST /v1/auth/introspect (see Token introspection).

Unauthorized

A missing or invalid token returns 401 with a WWW-Authenticate challenge naming the failure reason:

{
  "error": {
    "code": "unauthorized",
    "details": { "error": "missing_token" },
    "message": "A valid bearer token is required."
  },
  "ok": false
}