# Authentication

Every request to `/api/v2` is authenticated. Pass an API token as a bearer token in the `Authorization` header; Archive validates it on every request. There are no unauthenticated operations.

```http
Authorization: Bearer <your-token>
WORKSPACE-ID: <workspace-uuid>
```

The `WORKSPACE-ID` header is required only for workspace-scoped operations. See the [Workspaces guide](/api/v2/docs/guides/workspaces). The `Authorization` header is required on every request. Here is a complete request with both headers:

```graphql
query WorkspaceDefault {
  workspace {
    id
    name
  }
}
```

```http
Authorization: Bearer docs_demo_token_0000000000000000000000
WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a
```

## Creating a token

Create tokens from the **Integration tab** in the Archive app. You don’t need to contact support.

- If your workspace belongs to an **organization**, the token works across every workspace in the organization. Select the workspace per request with the `WORKSPACE-ID` header.
- Otherwise, the token is scoped to the single workspace it was issued for.

The full token is displayed only once, when you create it. Archive stores a hash and the last four characters, so you can identify a token by its last four characters later, but you can’t retrieve the full value again. Store it in a secret manager as soon as you create it.

> **Lost tokens can't be recovered**
>
> If you lose a token, create a new one. Creating a new token rotates the credential: the fresh token takes effect immediately and the previous one stops working.

## Rotating and disabling tokens

Re-provisioning from the Integration tab rotates the token. The new token takes effect immediately and the old one stops working, so you can rotate as soon as you suspect a token has been exposed. A rotated token fails with HTTP 401 and the body `{"errors":"Missing or invalid authentication token"}`, the same response returned for an unrecognized token.

Pausing is separate from rotating. A token paused from the Integration tab keeps its identity but is refused with HTTP 401 and the body `{"errors":"Account is disabled"}`. If you rotate a paused token, the replacement is issued paused too. Re-enable it before use.

## Token security

- **Keep tokens server-side.** Never ship a token to a browser, mobile app, or any other client you don’t control.
- **Store tokens in environment variables or a secret manager**, not in source control.
- **Rotate tokens if you suspect exposure.** Rotation takes effect immediately and doesn’t require contacting support.
- **Identify tokens by their last four characters.** The Integration tab shows the last four characters of each token, so you can tell which one to rotate without exposing the full value.

> **Building an agent?**
>
> Archive also exposes an MCP server at `/api/v2/mcp` for agent clients. This guide covers the direct GraphQL endpoint; MCP is a separate surface with its own connection flow.

For the error responses returned when authentication fails, see the [Errors guide](/api/v2/docs/guides/errors).