---
title: Personal access tokens API
description: List token metadata, mint a scoped secret once, and revoke a PAT without exposing stored credentials.
species: reference
---
# Personal access tokens API

PAT management requires `apps:manage`. A caller can mint only scopes allowed by both its own scope set and the current organization role.

## List tokens

```endpoint
GET /pats
```

Returns metadata such as id, name, scopes, creator, creation time, optional expiry, and revocation state. Secrets are never returned by list or fetch operations.

## Create a token

```endpoint
POST /pats
```

Send a name, requested scopes, and optional expiry. The response returns `201`, a `Location` header, and the `pat_...` secret exactly once.

```json
{
  "name": "skycrane reporting",
  "scopes": ["query:read", "data:read"]
}
```

Store the secret immediately. Supernova stores its hash and cannot recover the original. Invalid bodies return `400 invalid_pat_parameters` with a named `param` when possible.

## Revoke a token

```endpoint
DELETE /pats/{id}
```

Revocation prevents the PAT from authenticating future requests. It does not cancel a query or send already accepted under that principal; use the relevant resource endpoint for active work.

A token id outside the caller's organization is indistinguishable from an unknown id. Rotate a credential by creating the replacement, updating clients, verifying `GET /whoami`, then revoking the old PAT.