Skip to main content

​
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 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.
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.

​
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.
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.

​
Use a PAT to call the API

Send the token as a Bearer credential in the Authorization header on every request:
In Python:
For end-to-end examples, see:

​
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.
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 section of the API reference for the full schemas. 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.