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

# Personal Access Tokens

> Create, use, and revoke long-lived Personal Access Tokens (PATs) so scripts, CI jobs, and external services can call the Genesis REST API as you.

## Overview

A **Personal Access Token (PAT)** is a long-lived bearer token that lets
scripts, CI pipelines, and external integrations call the Genesis REST API
without going through an interactive sign-in. Each PAT is scoped to **one
user**: any request authenticated with the PAT runs as that user, with the
user's existing roles, RBAC permissions, and per-agent access.

PATs are the recommended credential for:

* CI / build pipelines (automation, deploy, smoke tests),
* local development scripts and `curl` calls,
* server-to-server integrations that drive Genesis agents,
* scheduled jobs that call the REST API on your behalf,
* the [`/api/tool_call`](/docs/Genesis-API/Tool-Call-Endpoint) endpoint
  for headless tool execution.

PATs are **not** the right credential for:

* Browser dashboard access — that uses your normal Auth0 / OIDC session.
* Snowflake SPCS deployments calling from external apps with Snowflake
  key-pair auth — those use the JWT → OAuth flow scoped to the SPCS
  ingress.
* Genesis Apps — those run server-side and use the signed
  `X-Genesis-App-Token` automatically.

<Note>
  PAT values look like `gp_<random>` and are checked by the Genesis auth
  middleware. They are stored hashed (SHA-256), never logged, and shown in
  plaintext **exactly once** at creation time. There is no recovery path —
  if you lose a PAT, revoke it and create a new one.
</Note>

## Create a PAT in the dashboard

1. Open the Genesis dashboard.
2. Click your avatar in the top-right and choose **API Keys**.
3. In **Create a new key**:
   * Enter a **Name** (anything human-readable, for example
     `ci-pipeline`, `local-dev-laptop`, `airflow-prod`). This is for your
     reference only.
   * Pick an **Expires** window (`30`, `90`, or `365` days). Pick the
     shortest window that works for you.
4. Click **Create**.
5. **Copy the displayed token immediately.** It is shown in a one-time
   reveal box and disappears as soon as you close the modal.

The same dialog lists every PAT you currently own and lets you revoke any
of them.

With authentication enabled, create a PAT from your own signed-in account. A
PAT, machine token, GenesisApp token, sandbox thread token, or agent call cannot
mint another PAT. With authentication disabled, the local operator can still
create one.

<Warning>
  Treat a PAT like a password. Anyone with the token can call the REST
  API as you, with all your permissions. Store it in a secrets manager
  (CI secrets, AWS Secrets Manager, `.env` files outside source control,
  etc.) and never commit it.
</Warning>

## Use a PAT to call the API

Send the token as a `Bearer` credential in the `Authorization` header on
**every** request:

```http theme={null}
GET /api/bots
Authorization: Bearer gp_eXAMPLE.....
```

```bash theme={null}
export GENESIS_PAT="gp_eXAMPLE....."
export GENESIS_URL="https://<your-genesis-host>"

curl -sS -H "Authorization: Bearer $GENESIS_PAT" \
  "$GENESIS_URL/api/bots"
```

In Python:

```python theme={null}
import os, requests

BASE = os.environ["GENESIS_URL"].rstrip("/")
HEADERS = {"Authorization": f"Bearer {os.environ['GENESIS_PAT']}"}

resp = requests.get(f"{BASE}/api/bots", headers=HEADERS, timeout=10)
resp.raise_for_status()
print([b["bot_id"] for b in resp.json()["data"]])
```

For end-to-end examples, see:

* [Chat with agents over REST](/docs/Genesis-API/Chat-Endpoints)
* [Call any tool with `tool_call`](/docs/Genesis-API/Tool-Call-Endpoint)
* [Manage document indexes over REST](/docs/Genesis-API/Document-Index-Endpoints)

## Identity, RBAC, and audit

Requests authenticated by a PAT run **as the user that owns the PAT**:

* The user's roles and `Permission` checks apply normally — for example,
  creating or deleting a document index requires
  `manage_document_indexes`, and managing other users' PATs requires
  `manage_users`.
* Per-agent RBAC applies, so the user must have access to a bot before
  they can chat with it via PAT.
* Audit logs and `last_used_at` reflect the owning user.
* A Prover approval can be made with your own PAT when your account has
  `view_connections` and is recorded as your
  decision, labelled `via personal access token`; disposition packages and
  bundles mark approval of your own proposal as `self_approved`, and so does a
  view test case approval made with the sign-in that asked for it. An MCP client
  calling the Prover API with your PAT carries the same owner attribution. An
  agent's own tool call, a system identity, and an app-only machine token cannot
  approve Prover decisions. See
  [Prover roles and approvals](/docs/Genesis-Prover/Roles-And-Approvals).

PATs are person-owned bearer credentials, even when an automation uses them.
Do not use a PAT as a machine identity for Prover approvals: it signs as the
person who owns it. Use a machine or app credential for machine-only work; those
credentials cannot approve Prover decisions.

## List, revoke, and admin operations

Most users only need the dashboard. The same operations are also
available over REST — see the
[PAT endpoints](/docs/Genesis-API/API-Reference#personal-access-token-endpoints)
section of the API reference for the full schemas.

| Action | UI | REST |
| - | - | - |
| Create a PAT | Avatar → **API Keys** → **Create** | `POST /api/auth/pats` |
| List your PATs | Avatar → **API Keys** | `GET /api/auth/pats` |
| Revoke one of your PATs | Avatar → **API Keys** → **Revoke** | `DELETE /api/auth/pats/{pat_id}` |
| List every user's PATs (admin) | — | `GET /api/auth/pats/admin` (`manage_users`) |
| Revoke any user's PAT (admin) | — | `DELETE /api/auth/pats/admin/{pat_id}` (`manage_users`) |

`last_used_at` is updated by the auth layer at most once every few
minutes per token, so it can trail real usage by a short window. Revocation
is immediate and propagates within seconds.

## Security guidance

* **Use short expirations** for PATs (30 or 90 days) and rotate them. Use
  longer expirations only when an established owner-rotation process governs
  the token.
* **Store PATs in a secret manager**, not in `.env` files committed to
  Git, not in chat messages, not in screenshots.
* **Scope by user, not by capability.** Today PATs use a wildcard scope;
  the effective privileges come from the owning user's roles. Give
  service accounts the **minimum** roles they need.
* **Revoke on suspicion of compromise.** Use the dashboard or `DELETE
  /api/auth/pats/{pat_id}` to invalidate a token immediately.

## Related pages

* [Chat with agents over REST](/docs/Genesis-API/Chat-Endpoints)
* [Call any tool with `tool_call`](/docs/Genesis-API/Tool-Call-Endpoint)
* [Manage document indexes over REST](/docs/Genesis-API/Document-Index-Endpoints)
* [API Reference — Personal access token endpoints](/docs/Genesis-API/API-Reference#personal-access-token-endpoints)
* [Users and Roles](/docs/Setup/Users-And-Roles)