---
title: Authenticating to Kvarm
description: Personal access tokens and repository-scoped agent tokens for git, the REST API and MCP.
canonical: https://kvarm.dev/auth.md
---

# Authenticating to Kvarm

## Discover

Every authenticated surface (git smart HTTP, `https://kvarm.dev/api/v1`, `https://kvarm.dev/mcp`) accepts the same bearer tokens. Public repositories are readable without one. The contract is at [https://kvarm.dev/openapi.json](https://kvarm.dev/openapi.json).

## Pick a method

| token | prefix | for |
| --- | --- | --- |
| Personal access token | `kvarm_pat_` | a person, or an agent acting as that person; scopes `read`, `write`, `api`, `ci` |
| Agent token | `kvarm_agt_` | one agent principal on one repository, with a role (`read` or `write`), ref patterns it may push (for example `refs/heads/agents/*`) and an expiry |

Prefer an agent token: it is limited to one repository, the refs it may update and a lifetime, and it is further capped by the current role of the person who minted it.

## Register and claim

A person signs in at [https://kvarm.dev/auth/login](https://kvarm.dev/auth/login) and creates tokens at [https://kvarm.dev/settings/tokens](https://kvarm.dev/settings/tokens). Agent principals are created with `POST /api/v1/agents` (`kvarm agents create`) and receive tokens from a person who can manage them. Tokens are shown once, at creation. Agent credentials cannot create agents or mint tokens.

## Use

```sh
curl -H "Authorization: Bearer $TOKEN" https://kvarm.dev/api/v1/user
git clone https://x-token:$TOKEN@kvarm.dev/<owner>/<repo>.git
```

MCP clients send the same `Authorization: Bearer` header to `https://kvarm.dev/mcp`.

## Errors

Errors are JSON: `{"error": "...", "code": "..."}`. `401 UNAUTHENTICATED` means no valid token; `403` means the token lacks the scope, role or ref pattern; a private repository you cannot read answers `404`, exactly like a missing one. `429` carries `Retry-After`.

## Revoke

Revoke a personal access token at [https://kvarm.dev/settings/tokens](https://kvarm.dev/settings/tokens); agents and agent tokens are revoked from the same page or the API. Revocation applies to the next request.