Authenticate with the Registry API

The Agent Volumes Registry API uses registry-local, resource-scoped bearer tokens for protected write operations. Tokens are opaque to clients — the bibliotheca derives authorization decisions from its own local state based on the token subject, the requested action, and the target resource. Token issuance is not standardized in v0.1; consult your bibliotheca’s documentation for how to obtain a token.

Which operations require authentication

Operation	Auth required	Portable authorization semantics
Search	No	N/A
Fetch release metadata	No	N/A
Download	No	N/A
Version index	No	N/A
Capability metadata	No	N/A
Trust metadata (summary + detail)	No	N/A
Advisory discovery	No	N/A
Publish	Yes (Bearer token)	Authorized to publish the volume identity or namespace
Unpublish	Yes (Bearer token)	Authorized to unpublish the volume identity or exact release
Trust upload	Yes (Bearer token)	Authorized to add trust attachments for the exact release

Passing the token

Include the bearer token in the Authorization header on every authenticated request.

POST /api/v1/volumes/my-volume
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "version": "1.0.0",
  "mediaType": "application/gzip"
}

The token value is an opaque string. Do not parse or decode it — treat it as a credential you pass verbatim.

Token format

Bearer tokens are:

Opaque — clients must not parse or decode the token value
Registry-local — tokens issued by one bibliotheca are not valid on another
Resource-scoped — a token may be authorized for a specific scope, volume, or release; the bibliotheca enforces the scope boundary

Error responses

If the token is missing, malformed, unknown, expired, or revoked, the bibliotheca returns 401 Unauthorized:

{
  "type": "https://agentvolumes.org/problems/authentication-required",
  "title": "Authentication required",
  "status": 401,
  "detail": "Bearer token is missing or invalid."
}

If the token is valid but the caller lacks the needed permission for the requested action or resource, the bibliotheca returns 403 Forbidden:

{
  "type": "https://agentvolumes.org/problems/authorization-failed",
  "title": "Authorization failed",
  "status": 403,
  "detail": "This token is not authorized to publish to @acme/my-volume."
}

A 401 means authentication failed — the token itself is the problem. A 403 means authentication succeeded but the token lacks permission for this specific operation or resource.

Authenticated request example

The following example creates a release upload intent for a scoped volume:

POST /api/v1/volumes/@acme/research-agent-pack
Authorization: Bearer eyJhbGc...
Content-Type: application/json

{
  "version": "2.0.0",
  "mediaType": "application/gzip",
  "declaredDigest": "sha256:a3f2b8c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
}

Token issuance — how you register, log in, or generate API tokens — is bibliotheca-local and is not standardized in Agent Volumes v0.1.

​Which operations require authentication

​Passing the token

​Token format

​Error responses

​Authenticated request example

Which operations require authentication

Passing the token

Token format

Error responses

Authenticated request example