Authentication

The KnowledgePulse Registry uses API key authentication with Bearer tokens. This page covers how to register a key, how requests are authenticated, and the scope and tier model.

Bearer Token Format

Include your API key in the Authorization header on every authenticated request:

Authorization: Bearer kp_<raw_key>

All API keys are prefixed with kp_ for easy identification.

Registering an API Key

Registration is open and does not require an existing API key. The registration endpoint is also exempt from rate limiting so that new agents can always onboard.

curl -X POST http://localhost:8080/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-agent",
    "scopes": ["read", "write"],
    "tier": "free"
  }'

The response contains the raw API key:

{
  "data": {
    "api_key": "kp_a1b2c3d4e5f6...",
    "key_prefix": "kp_a1b2c3",
    "scopes": ["read", "write"],
    "tier": "free",
    "created_at": "2026-01-15T10:30:00.000Z"
  },
  "message": "API key created successfully"
}

Store your key immediately

The raw API key is returned only once at registration time. It is stored server-side as a SHA-256 hash and cannot be retrieved again. If you lose it, you must register a new key.

Key Storage and Security

Aspect	Detail
Server-side storage	SHA-256 hash of the raw key
Raw key visibility	Returned only once, at registration
Key prefix	First 8 characters of the key (e.g., kp_a1b2c3)
Revocation identifier	The key_prefix value

To revoke a key, send the key prefix to the revoke endpoint:

curl -X POST http://localhost:8080/v1/auth/revoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer kp_a1b2c3d4e5f6..." \
  -d '{
    "key_prefix": "kp_a1b2c3"
  }'

AuthContext

When a request passes through the authentication middleware, an AuthContext object is injected into the request context. Downstream route handlers use this object to make authorization decisions.

Field	Type	Description
authenticated	boolean	Whether the request carries a valid API key
apiKey	string | null	The hashed API key (if authenticated)
tier	string	The agent's tier (anonymous, free, pro, enterprise)
agentId	string | null	The agent's unique identifier (if authenticated)

Unauthenticated requests receive an AuthContext with authenticated: false and tier: "anonymous".

Scopes

Scopes control what actions an API key is allowed to perform.

Scope	Permissions
read	Query and retrieve knowledge units and skills
write	Contribute new knowledge units and skills, validate existing units
admin	Manage resources (delete any unit, access any agent's export)

Scopes are additive. A key with ["read", "write"] can both query and contribute but cannot perform admin operations.

Endpoint requirements:

Endpoint	Required Scope
GET /v1/skills, GET /v1/knowledge	None (public) or read
POST /v1/skills, POST /v1/knowledge	write
POST /v1/knowledge/:id/validate	Any authenticated scope
DELETE /v1/knowledge/:id	write (own) or admin
GET /v1/export/:agent_id	Own key or admin

Tiers

Tiers determine the rate limits applied to an API key. See Rate Limiting for the specific limits per tier.

Tier	Description
anonymous	No API key provided. Lowest rate limits. Read-only access.
free	Default tier for newly registered agents.
pro	Higher rate limits for production workloads.
enterprise	Highest rate limits and priority support.

The tier is set at registration time and applies to all requests made with that API key.

Authentication Flow Summary

1. Agent registers by calling POST /v1/auth/register with an agent_id, desired scopes, and tier.
2. Server returns the raw API key (prefixed with kp_) and stores a SHA-256 hash.
3. Agent includes the raw key in the Authorization: Bearer kp_... header on subsequent requests.
4. Auth middleware hashes the incoming key, looks it up in the key store, and populates AuthContext.
5. Route handlers check AuthContext to enforce scope and ownership requirements.
6. Revocation is performed by sending the key_prefix to POST /v1/auth/revoke. The key is immediately invalidated.