# Access tokens

> Field reference for personal access tokens (PATs) in the Agent Gateway dashboard: where they live, the token form and its scopes, the created-token page, and revoking a token.

A personal access token (PAT) is a long-lived bearer credential that lets automation, such as a script or a CI job, call the Agent Gateway management API directly, outside an interactive dashboard session.

## Overview

Access tokens live on the Access Tokens (PAT) tab of the Secrets page. The tab appears only for users whose role can view access tokens, which by default means administrators. The same default applies to creating, editing, and revoking tokens.

Every token is bound to the user who creates it, shown as the token’s Bound user. A token acts as that user and can do at most what that user’s role allows. Its scopes narrow that role to the features the automation needs: the token’s effective permissions are the features that both the bound user’s role and the token’s scopes include. A token with no scopes holds the bound user’s full role. To change the most a token can do, change the bound user’s role. See [Roles](/products/affinidi-trust-fabric/agent-gateway/reference/configuration/settings.md#roles).

A few administrative actions check only the bound user’s role and ignore a token’s scopes: managing users, changing settings, backup and restore, and exporting storage.

- Give each automation its own token, so revoking one leaves the others working.

- Pick only the scopes the automation needs, such as surfaces.view for a read-only monitoring script. Leaving scopes empty is the broadest choice.

- Set an expiry for a token that serves a short-lived job. The expiry is fixed when the token is created.

- Leave Advanced resource scoping empty for automation that changes records created in the dashboard. A token with a Resource pattern has read-only access to those records.

## Access tokens list

The Access Tokens (PAT) tab lists access tokens ten to a page, newest first. It lists every user’s tokens. Open a token to see its Bound user. Revoked tokens are hidden until you turn on Show revoked. The filter box at the top of the Secrets page matches a token’s name, description, ID, or scopes.

| Column | What it shows |
| Name | The token’s name, with its description underneath. |
| Scopes | Up to three scopes, then a count of the rest. Full role when the token has no scopes. |
| Status | Active, Expired, or Revoked. |
| Last used | How long ago the token last authenticated a request, or Never. Updated at most once a minute. |
| Expires | The expiry date and time, or Never. |
| Created | How long ago the token was created. Hover for the exact time. |
| Actions | A revoke button, shown to users who can revoke tokens. |

Select New Access Token to open the Create Access Token form, or select a row to open Edit Access Token.

## Token fields

| Field | Required | Default | Description |
| Name | Yes | — | A label for the token, up to 120 characters. |
| Token ID | — | Generated | Shown on Edit Access Token only, read-only, with a copy button. |
| Description | No | Empty | What the token is used for, up to 280 characters. |
| Selected scopes | No | None, meaning the bound user’s full role | The features this token may use. Add scopes from Available scopes, which lists only the features your own role grants. Select Clear all to remove every scope. A scope outside your role, for example one preset by a creation link, is shown in red and must be removed before saving. |
| Expires at | When Never expires is off | Never expires on | Shown on Create Access Token only. Turning off Never expires fills in an expiry 24 hours after the form opened, in your local timezone. The expiry must be in the future and within 3650 days. It is fixed once the token is created. |

Token scopes are named after the dashboard feature and the action they allow, such as secrets.view, surfaces.edit, or policies.delete. The policies.view, policies.edit, and policies.delete scopes control access to policy definitions.

### Advanced resource scoping

Advanced resource scoping is a collapsible section of the token form. Leave it empty for a token that reaches every record its scopes allow. It opens automatically on a token that already uses it.

A tenant is a partition of the appliance’s records that a token’s Resource pattern selects through a required header. Records you create in the dashboard belong to no tenant. A token with a Resource pattern has read-only access to those records. A token with a Resource pattern or Required headers can set an A2A surface’s Message validation to any value except Off.

A banner at the top of the section shows Appliance-wide while Resource pattern is empty, and Tenant selected by a named header once a pattern takes its tenant segment from a required header.

| Field | Required | Description |
| Resource pattern | No | Limits the token to records whose canonical resource target matches the whole pattern. Leave blank for no ID restriction. A non-blank pattern takes the form TENANT:${<header>}:<resource-kind>:<resource-id-pattern>, naming exactly one header from Required headers. Wrap several resource selectors in a single non-capturing group, such as (?:secrets:.*|surfaces:.*). Up to 512 characters. |
| Required headers | No | Headers every request with this token must carry. Select Add header to add one, up to eight. Each has a Header name (letters, digits, and dashes, up to 64 characters) and a Validation pattern (a regular expression the whole header value must match, up to 256 characters). |

Resource kinds are secrets, certificates, api-keys, surfaces, gateways, connection-points, mediators, mcp-proxies, a2a-proxies, trust-registries, issuers, authorities, integrations, policy-definitions, surface-templates, credential-providers, jwt-verification-strategies, and sts-clients. Integrations, endpoints, and event sets belong to the whole appliance, so a token with a Resource pattern is refused on every integrations request. Leave Resource pattern empty on a token that manages integrations.

Test this scope appears under the fields once a pattern or header is set. Enter a sample value for each required header, choose a Resource kind, and type a Sample entity ID. The preview shows the Canonical target it built and whether the token would be allowed or denied, and lists any problem with the pattern or headers.

## Copy creation link

Copy creation link sits at the bottom of the token form, on both Create Access Token and Edit Access Token. It copies a link to a new token form prefilled with the current name, description, scopes, expiry, resource pattern, and required headers, so you can share a token configuration or reuse it later. Copying from an existing token leaves that token unchanged.

The token is created only when the person opening the link selects Create token, and it is bound to them. Scopes outside their role appear in red and block creation until removed. If the resource pattern, a required header, or the expiry is invalid when you copy, the link is still copied, and a warning says the form it opens needs those settings fixed before it creates a token.

## Created token page

After you select Create token (or Save at the top of the page), the Access Token Created page shows the new token’s secret once.

| Element | Description |
| Token secret | Shown masked as agpat_ followed by dots. The secret is available on this page only. |
| Copy | Copies the real secret to the clipboard. If copying fails, for example because the browser blocks clipboard access, an error appears and the field shows the secret so you can select and copy it by hand. |
| Done | Returns to the access tokens list. |

Secret hygiene

Store the token secret in your secrets manager and inject it into the automation at runtime, rather than hardcoding it in source code or configuration files. Keep it out of logs and debug output. If a secret may have been exposed, revoke the token and create a new one.

## Editing a token

Edit Access Token changes a token’s name, description, scopes, and resource scoping. Select Save changes (or Save at the top of the page). The token keeps its ID, secret, and expiry.

The Access Token Details card beside the form shows the Bound user, Status, Created, Last used, and Expires values. A revoked token opens read-only, with the message Revoked tokens are immutable.

## Revoking a token

Select Revoke token at the bottom of Edit Access Token, or the revoke button on the token’s row in the list, then select it again to confirm. The token stops authenticating at once and its status changes to Revoked. Revoking a token also revokes any tokens that automation created with it. Revocation is permanent, so create a new token if the automation still needs access.

To replace a token’s secret, create a token with the same settings, for example from its Copy creation link, move the automation to it, then revoke the old token.

## Related

- [Secrets](/products/affinidi-trust-fabric/agent-gateway/reference/authentication/secrets.md): the Secrets page that holds the Access Tokens (PAT) tab.

- [Settings](/products/affinidi-trust-fabric/agent-gateway/reference/configuration/settings.md#roles): the Administrator, Power User, and User roles that cap what a token can do.

- [API keys](/products/affinidi-trust-fabric/agent-gateway/reference/authentication/api-keys.md): keys that authenticate external clients calling a surface, rather than the management API.