Personal Access Tokens
Overview
Personal Access Tokens (PATs) provide named, scoped, time-limited tokens for programmatic API access. They are distinct from the existing Token model, which continues to serve UI/session authentication. PATs use the w_ prefix to distinguish them from OIDC JWT tokens.
Token Format
Format: w_<unix_timestamp>_<random> (e.g., w_1735689599_Abc123def...)
w_prefix identifies the token as a Waldur PAT<unix_timestamp>is the expiration time, visible by inspecting the token<random>is 256 bits of entropy viasecrets.token_urlsafe(32)- SHA-256 hash stored in database; plaintext shown only once at creation
- First 8 characters stored as
token_prefixfor UI identification
The embedded timestamp allows humans and scripts to check expiry without an API call. The server still validates against the database on every request.
Authentication
PATs use the Authorization: Bearer header:
1 | |
The PATAuthentication class in waldur_core.core.authentication handles PAT requests. It is registered in DEFAULT_AUTHENTICATION_CLASSES between SessionAuthentication and OIDCAuthentication:
1 2 3 4 5 6 | |
The w_ prefix lets PATAuthentication claim the request and fall through to OIDCAuthentication for non-PAT Bearer tokens.
API Endpoints
Base URL: /api/personal-access-tokens/
| Method | Path | Description |
|---|---|---|
| GET | /api/personal-access-tokens/ |
List user's tokens (no plaintext) |
| POST | /api/personal-access-tokens/ |
Create a new token (plaintext returned once) |
| GET | /api/personal-access-tokens/{uuid}/ |
Retrieve token details (no plaintext) |
| DELETE | /api/personal-access-tokens/{uuid}/ |
Soft-revoke (sets is_active=False) |
| POST | /api/personal-access-tokens/{uuid}/rotate/ |
Atomic rotation: creates new token, revokes old |
| POST | /api/personal-access-tokens/{uuid}/set_network_acl/ |
Replace the token's source-network allowlist |
| GET | /api/personal-access-tokens/available_scopes/ |
Lists all delegatable permission enum values |
PUT and PATCH are disabled -- tokens are immutable after creation.
Create Token
POST /api/personal-access-tokens/
Needs a re-authentication grant for create_personal_access_token in the X-Reauthentication-Grant header (see Re-authentication).
Request:
1 2 3 4 5 | |
Response (201, with Cache-Control: no-store header):
1 2 3 4 5 6 7 8 | |
Rotate Token
POST /api/personal-access-tokens/{uuid}/rotate/
Atomically revokes the old token and creates a new one with the same name, scopes, and expiration. The operation uses select_for_update() to prevent races. Like create, it needs a re-authentication grant for create_personal_access_token. Returns the same response format as create.
Revoke Token
DELETE /api/personal-access-tokens/{uuid}/
Sets is_active=False on the token (soft delete). Returns 204.
Scope Enforcement
PAT scopes follow an intersection model: the effective permission at request time is the intersection of the PAT's scopes and the user's current roles.
1 | |
Key implementation details in waldur_core.permissions.utils:
_pat_scope_check()runs in bothhas_permission()andhas_any_permission()before theis_staffbypass, so staff PATs are properly scoped- If a user loses a role after creating a PAT, the PAT's matching permissions stop working immediately
- Scope validation at creation ensures users can only request permissions they currently have
Staff and support checks
A staff user's PAT acts as staff only with the STAFF.ACCESS scope, and as
support only with STAFF.ACCESS or SUPPORT.ACCESS. A check that lets staff
or support through must therefore ask the request, not the user:
has_staff_access(request)andhas_support_access(request)inwaldur_core.core.permissions, or the permission classes built on them (IsStaff,IsSupport,IsStaffOrSupportUser,PATScopeAwareIsAdminUser)- the function permissions
structure_permissions.is_staffandis_staff_or_support, which call them
A token that lacks the scope its user's role needs also reads as the user without
that role. PATAuthentication hands such a request a TokenScopedUser, a proxy of
User whose is_staff and is_support read as the token allows:
| Account | Token carries | is_staff |
is_support |
|---|---|---|---|
| staff | neither scope | false | false |
| staff | SUPPORT.ACCESS only |
false | true |
| support | neither scope | false | false |
Every check on the user's flags follows the token, without the check changing:
filter_queryset_for_user, GenericRoleFilter, serializer get_fields, media
access rules and the staff bypass in has_permission. Such a token therefore
sees and does only what the user's roles allow. /api/users/me/ reports the
flags the token acts with.
The proxy never writes the narrowed flags: save, delete and
refresh_from_db run as a plain User, so the database and receivers of User
signals see the account's flags; save leaves is_staff / is_support out; and
assigning them raises. account_is_staff / account_is_support read the account's
flags, which TokenCarriesUserRole needs. A task given the user, or its id, loads
it again and sees the account's flags.
Credentials in GET /api/service-settings/ are the exception: a token sees them
only with STAFF.ACCESS or, for an organization owner, with
OFFERING.UPDATE_INTEGRATION, the permission guarding the same values on an
offering. Its bindings must cover the organization in both cases, so a bound
token never sees the credentials of settings that belong to no organization. A
staff token without STAFF.ACCESS reads as not staff, so it sees these settings
only as far as its user's roles reach. Any other token gets the redacted options a non-owner sees. Use check_pat_permission for a check
that decides the role itself and needs only the token's limits on top.
Security
PAT-via-PAT Blocked
The create, destroy, rotate, and set_network_acl actions reject requests authenticated with a PAT. This prevents token escalation -- PATs can only be managed through session or token authentication.
Re-authentication
Creating a token, rotating one, and widening a token's network ACL (see Network ACLs) each need a re-authentication grant: proof that the user has just confirmed who they are, which holding their session or API token alone is not. Without a valid grant the request gets a 401 whose body has "code": "reauthentication_required", the action the grant must be for, and the methods the user can confirm with.
Get a grant for that action, then send it in the X-Reauthentication-Grant header of the request:
- Password:
POST /api/reauthentication/password/with{"action": "<action>", "password": "<current password>"}. The 201 response carries thegrantand itsexpires_at. - Passkey:
POST /api/reauthentication/passkey/begin/with{"action": "<action>"}returns a WebAuthn challenge;POST /api/reauthentication/passkey/finish/with theaction, theceremonyand the signedcredentialreturns the grant.
The actions are create_personal_access_token (create and rotate) and widen_personal_access_token_networks. A grant is single-use, bound to the user and to one action, and expires after REAUTHENTICATION_GRANT_LIFETIME_SECONDS. A grant is neither issued nor accepted for a request that is not the user's own sign-in: staff impersonating the user, a personal access token and an OIDC access token get 403.
Resource API keys are never revealed
GET /api/marketplace-resource-api-keys/{uuid}/reveal/ refuses every PAT,
whatever its scopes and bindings: a revealed key is a live credential, and a
script's token is not trusted with one. A PAT also cannot rotate or retry a
key as its assignee. A bound PAT lists only the keys of resources its bindings
reach. See Resource API keys.
Uniform Error Responses
All authentication failures return the same "Invalid token." message regardless of the failure reason (inactive, expired, nonexistent). This prevents information leakage about token state.
User Deactivation Cascade
The revoke_user_pats_on_deactivation signal handler in waldur_core.core.handlers revokes all active PATs when a user's is_active changes from True to False.
Global Kill Switch
The PAT_ENABLED setting (default: True) controls whether PAT authentication is active. When False, PATAuthentication.authenticate() returns None for all w_-prefixed tokens, effectively disabling all PATs system-wide.
Configuration
Settings
| Setting | Default | Description |
|---|---|---|
PAT_ENABLED |
True |
Global enable/disable for PAT authentication |
PAT_MAX_LIFETIME_DAYS |
365 |
Maximum token lifetime in days |
PAT_MAX_TOKENS_PER_USER |
20 |
Maximum active tokens per user |
These settings are in the "Personal Access Tokens" fieldset of the settings page in the Waldur admin (Configuration → Settings).
Model
PersonalAccessToken in waldur_core.core.models:
| Field | Type | Description |
|---|---|---|
user |
ForeignKey(User) | Token owner |
name |
CharField | User-assigned name |
token_prefix |
CharField | First 8 chars of token (for UI display) |
token_hash |
CharField(64) | SHA-256 hash (unique, indexed) |
scopes |
JSONField | List of PermissionEnum values |
expires_at |
DateTimeField | Expiration timestamp |
is_active |
BooleanField | Whether the token is active |
last_used_at |
DateTimeField | Last usage timestamp |
last_used_ip |
GenericIPAddressField | Last client IP |
use_count |
PositiveIntegerField | Total usage count |
Usage Tracking
The last_used_at, last_used_ip, and use_count fields are updated via a batched write with 10-minute cache-based debouncing (cache key: pat_usage:{pk}). This avoids a database write on every authenticated request.
Audit Events
| Event Type | Trigger |
|---|---|
pat_created |
Token created |
pat_revoked |
Token revoked (manual or user deactivation cascade) |
pat_rotated |
Token rotated |
pat_expired |
Token expired (deactivated by cleanup task) |
pat_used_from_new_ip |
Token used from a different IP than last_used_ip |
pat_access_denied_from_ip |
Request rejected because the source address is outside the token's network ACL |
pat_network_acl_updated |
Token's network ACL replaced via set_network_acl |
All events are scoped to the token's user and grouped under EventGroup.AUTH (via EVENT_GROUP_MAPPING) in waldur_core.logging.enums.
Celery Tasks
The cleanup_expired_personal_access_tokens task runs every 6 hours. It deactivates all PATs where expires_at <= now() and is_active=True, emitting a pat_expired event for each.
Examples
Get a re-authentication grant
Creating and rotating a token each need a fresh grant for create_personal_access_token:
1 2 3 4 | |
The grant in the response is used in the examples below as YOUR_GRANT. It is single-use: get a new one for each change.
Create a PAT
1 2 3 4 5 6 7 8 9 | |
Use the PAT
1 2 | |
Rotate a PAT
1 2 3 | |
Revoke a PAT
1 2 | |
Network ACLs
A token can be restricted to a set of source networks. allowed_networks takes a list of CIDR strings; bare addresses are widened to /32 or /128. An empty list (the default) means the token is unrestricted. The number of entries is capped by the PAT_MAX_ACL_ENTRIES setting.
Set the ACL at creation time:
1 2 3 4 5 6 | |
To change the ACL of an existing token, use the set_network_acl action:
POST /api/personal-access-tokens/{uuid}/set_network_acl/
1 | |
A dedicated action is used rather than PATCH because PUT and PATCH stay disabled on the viewset, and the change is recorded as its own pat_network_acl_updated audit event.
Narrowing the ACL needs nothing more. A change narrows it when every new network lies inside a current network of the same address family, when it restricts an unrestricted token, or when it leaves the list as it is. An IPv6 network never counts as inside an IPv4 one.
Any other change widens the ACL: adding a network, replacing one with a broader one, or clearing the list, which lets the token work from anywhere. Widening needs a re-authentication grant for widen_personal_access_token_networks, sent in the X-Reauthentication-Grant header, as creating or rotating a token does. Without one the request gets the 401 reauthentication_required challenge and the ACL stays as it was. See Re-authentication for how to get a grant.
Widening is refused (403) to any caller that is not the user's own sign-in: staff impersonating the user, an OIDC access token, or any other delegated credential. A personal access token gets 403 for every change to the ACL, narrowing included, as for the other token management actions.
To widen an ACL, get a grant for widen_personal_access_token_networks and send it with the new list:
1 2 3 4 5 | |
The action takes the same row lock as rotate, so a concurrent rotation cannot copy a stale ACL onto the new token, and it decides whether a change widens against the locked row. Setting the ACL of an inactive token returns 400.
A request from outside the ACL is rejected with the same generic Invalid token. error as any other authentication failure -- the response never confirms that the token itself is valid. The rejection is recorded as a pat_access_denied_from_ip audit event with the source address (debounced per token and source IP).
Enforcement fails closed: if the source address cannot be determined, a token with a non-empty ACL is rejected.
A known token presented after it should no longer work -- revoked, or with a deactivated owner, or an owner no longer permitted personal access tokens -- is rejected with the same generic error and recorded as a pat_authentication_rejected audit event carrying a reason (revoked, user_inactive, permission_revoked), debounced per token, reason and source IP. An expired token is rejected without an individual audit event (expiry is an expected lifecycle end, already surfaced by the pat_expired event the cleanup task emits, not a replay signal). An unknown token is never audited, so a forged bearer token cannot flood the event log.
Audit volume is additionally capped per token: PAT_MAX_AUDIT_EVENTS_PER_HOUR (default 50) limits how many events one token may generate per hour, counted separately for source-address changes and for rejections. Beyond the ceiling the events and the last_used_at / last_used_ip / use_count write are suppressed for the rest of the window and a warning is logged; the requests themselves are unaffected. The per-address debounce alone cannot bound this -- a caller with an IPv6 /64 has effectively unlimited source addresses.
Deployment requirement
Waldur resolves the client address from the first X-Forwarded-For entry, falling back to REMOTE_ADDR. This is the same resolver used across the platform (audit logging, AccessSubnet, marketplace filters) and matches the ingress whitelistSourceRange.
The network ACL is a security boundary, and it is only as strong as the trust boundary that populates X-Forwarded-For. Because the resolver takes the first entry, that entry must be written by a proxy you control, not by the caller:
- Safe (required): the edge proxy / ingress overwrites
X-Forwarded-Forwith the real client address on each request. The defaultnginxingress does exactly this out of the box (use-forwarded-headers: false), so the first entry is always the address that actually connected to the load balancer. - Unsafe — defeats the ACL: any proxy in front that is configured to trust and append to an incoming
X-Forwarded-For(for nginx ingress,use-forwarded-headers: true) without restricting that trust to known upstream proxies. In that mode a caller can sendX-Forwarded-For: <an-allowed-ip>and the spoofed value becomes the first entry, bypassing the ACL entirely (curl -H "X-Forwarded-For: 203.0.113.5" ...).
Do not enable forwarded-header trust/append mode unless the proxy accepting it is itself reachable only through a trusted, IP-restricted upstream that overwrites the header. The same caveat applies to AccessSubnet and marketplace IP filters, which share this resolver. Enforcement fails closed on an unresolvable address (a token with a non-empty ACL is rejected), but it cannot distinguish a spoofed first entry from a genuine one — that distinction is the proxy's job.
Audit attribution
Every audit event carries auth_method in its context -- session, pat, token, or oidc. PAT-authenticated requests additionally carry pat_uuid and pat_name, so an action can be traced to the specific token. Filter with /api/events/?auth_method=pat or /api/events/?pat_uuid=<uuid>.
See Also
- Service Accounts -- programmatic access at organizational/project scope
- Identity Bridge -- federated identity management