Authentication

kubbi's public API uses two authentication mechanisms: API keys for producers, and capability URLs (claim URLs) for consumers. Account and API key management happen in the dashboard at dashboard.kubbi.ai.

API keys

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

http

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. Create and manage them from Dashboard → API Keys.

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. The number of active keys you can hold depends on your plan.

Storing API keys securely

Use environment variables or a secrets manager (e.g., AWS Secrets Manager, Vault)
Never commit API keys to source control
Use .env files locally and add them to .gitignore
Rotate keys periodically, especially if you suspect exposure

If a key is compromised, revoke it from Dashboard → API Keys and create a new one. Existing kubbis created with the old key remain intact, but no new requests can be made with the revoked key.

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.

text

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

Mechanism	Used by	Endpoints
API key	Producers	/api/v1/kubbis/*
Claim URL	Consumers	/r/:claim_token