> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvolumes.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate with the Registry API

> How to obtain a bearer token and authenticate write operations like publish and trust uploads against an Agent Volumes bibliotheca.

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.

```http theme={null}
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`:

```json theme={null}
{
  "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`:

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

<Warning>
  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.
</Warning>

## Authenticated request example

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

```http theme={null}
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"
}
```

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