Authentication

kubbi uses three authentication mechanisms depending on the actor and the operation.

API keys

Producers authenticate with API keys. Pass the key as a Bearer token in the Authorization header.

POST /api/v1/kubbis HTTP/1.1
Host: api.kubbi.ai
Authorization: Bearer kb_your_api_key
Content-Type: application/json

API keys are scoped to the authenticated user. You can create and manage them via the dashboard or the auth endpoints:

• POST /auth/api-keys — create a new API key (requires JWT and a label)
• GET /auth/api-keys — list your API keys (requires JWT)

API keys use the prefix kb_. The full key is shown only once at creation. kubbi stores a SHA-256 hash of the key — the raw key cannot be recovered.

Treat API keys like passwords. Do not commit them to version control or share them in plain text. You can have up to 5 active keys per account.

JWT (account management)

Account-level operations (registration, login, API key management) are protected by JSON Web Tokens. Obtain a JWT by registering or logging in. JWTs expire after 30 days.

curl -X POST https://api.kubbi.ai/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'

curl -X POST https://api.kubbi.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'

Both return a JWT in the response body. Include it in subsequent requests as a Bearer token.

Claim URLs (consumer access)

Consumers do not need an API key or account. The claim URL is a capability URL — possession of it is sufficient to inspect metadata and claim the payload.

https://api.kubbi.ai/r/abc123xyz
                          └── claim token

The claim token is an unguessable string embedded in the URL. kubbi stores a SHA-256 hash of each token — the raw token exists only in the claim URL. Treat claim URLs as secrets — anyone who has one can claim the payload.

Summary