# Trust credentials

Last validated Jan 30, 2026

Trust credentials provide a framework for delegated and scoped access to the [Tailscale API][kb-api]. A trust credential creates access tokens for scoped API access, instead of using a fully-permitted access token which expires after 90 days (or less if the fully-permitted access token has a shorter expiry).

Trust credentials support the [principle of least privilege][ln-principle-of-least-privilege] by allowing fine-grained control on the access granted to the credential using scopes, unlike a fully-permitted access token which grants full access to the Tailscale API.

Trust credentials come in two forms: [OAuth clients][kb-oauth-clients] and [federated OIDC workload identities][kb-workload-identity] (or federated identities for short).

## Differences between OAuth clients and federated identities

OAuth clients and federated identities have a number of differences in the way they are used and additional setup required in external systems.
The table below highlights these differences and may be helpful for determining which option is correct for your use case.

OAuth clients
Federated identities

Secure usage

OAuth clients require using a long-lived client secret for generating Tailscale access tokens.
This long-lived secret must be stored securely, as it can be used to generate access tokens indefinitely until it is revoked.

Federated identities do not require storing long-lived secret material.
They instead require an established trust relationship with a third-party system, and a short-lived identity token generated by this system, to create Tailscale access tokens.

Required setup

OAuth clients require no additional setup or external integrations to generate credentials.
Only the client ID and client secret which are generated when creating the OAuth client are required for generating Tailscale access tokens.

Federated identities require setting up a trust relationship between Tailscale and a third-party system that is capable of generating OIDC-compliant JWT identity tokens to exchange for Tailscale access tokens.
Not all scenarios where you might want to access the Tailscale API with granularly scoped access tokens may support generating these JWT identity tokens for workload identity federation.

Information common to both forms of trust credentials is shared below.

## Scopes

> **Note:**
>
> Our scopes have changed to have more granular permissions associated with each scope. The previous set of scopes can be found in the [legacy scopes section][ar-legacy-scopes].

Scopes define which operations are permitted in API access tokens that are created by your trust credentials.

In addition to the endpoints listed below, all scopes allow access to `GET /api/v2/tailnet/:tailnet/keys/:keyID` for the key in use.

You can use the following scopes in Tailscale trust credentials:

Scope ID
Description
Allowed endpoints

all:read
The credential has read-only access to the tailnet. This scope is not restricted to only read access of APIs that existed at the time the credential was initially authorized—the all:read scope also grants read access to new APIs created in the future. The all and all:read scopes are the only scopes which can get a list of all access tokens which exist in the tailnet.

All `*:read` endpoints, even endpoints which did not exist when the credential was initially authorized.
GET /api/v2/tailnet/:tailnet/keys/:keyID (for any key, not just itself)

all
The credential has complete access to the tailnet. This scope is not restricted to only access of APIs that existed at the time the credential was initially authorized—the all scope also grants access to new APIs created in the future. The all and all:read scopes are the only scopes which can get a list of all access tokens which exist in the tailnet.

All endpoints, even endpoints which did not exist when the credential was initially authorized.
GET, DELETE /api/v2/tailnet/:tailnet/keys/:keyID (for any key, not just itself)

dns:read

The credential has access to read DNS settings.

GET /api/v2/tailnet/:tailnet/dns/nameservers

GET /api/v2/tailnet/:tailnet/dns/preferences

GET /api/v2/tailnet/:tailnet/dns/searchpaths

GET /api/v2/tailnet/:tailnet/dns/split-dns

dns

The credential has access to read and manipulate DNS settings.

Endpoints from dns:read

POST /api/v2/tailnet/:tailnet/dns/nameservers

POST /api/v2/tailnet/:tailnet/dns/preferences

POST /api/v2/tailnet/:tailnet/dns/searchpaths

PATCH, PUT /api/v2/tailnet/:tailnet/dns/split-dns

policy\_file:read

The credential has access to read and validate the tailnet policy file.
devices:posture\_attributes:read and devices:core:read are required when using this scope.

GET /api/v2/tailnet/:tailnet/acl

POST /api/v2/tailnet/:tailnet/acl/preview

POST /api/v2/tailnet/:tailnet/acl/validate

policy\_file

The credential has access to read, validate, and modify the tailnet policy file.
devices:posture\_attributes and devices:core:read are required when using this scope.

Endpoints from policy\_file:read

POST /api/v2/tailnet/:tailnet/acl

users:read

The credential has access to read user information.

GET /api/v2/tailnet/:tailnet/users

GET /api/v2/user/:userID

users

The credential has access to read user information, modify user roles, and handle user approval, suspension, deletion, and restoration.

Endpoints from user:read

POST /api/v2/user/:userID/role

POST /api/v2/user/:userID/approve

POST /api/v2/user/:userID/suspend

POST /api/v2/user/:userID/restore

POST /api/v2/user/:userID/delete

devices:core:read

The credential has access to read devices in the tailnet.

GET /api/v2/tailnet/:tailnet/devices

GET /api/v2/device/:deviceID

devices:core

The credential has access to read the list of all devices in the tailnet, authorize or remove machines, and manipulate tags on
devices. You must select one or more tags when you create a credential with the devices:core scope. Auth keys created with this credential must have
those exact tags, or tags owned by the credential's tags

Endpoints from devices:core:read

DELETE /api/v2/device/:deviceID

POST /api/v2/device/:deviceID/authorized

POST /api/v2/device/:deviceID/expire

POST /api/v2/device/:deviceID/ip

POST /api/v2/device/:deviceID/name

POST /api/v2/device/:deviceID/key

POST /api/v2/device/:deviceID/tags

devices:posture\_attributes:read

The credential has access to read device posture attributes.

GET /api/v2/device/:deviceID/attributes

GET /api/v2/device/:deviceID/attributes/:attributeKey

devices:posture\_attributes

The credential has access to manipulate and read device posture attributes.

Endpoints from devices:posture\_attributes:read

POST, DELETE /api/v2/device/:deviceID/attributes

POST, DELETE /api/v2/device/:deviceID/attributes/:attributeKey

devices:routes:read

The credential has access to read subnet router settings and exit node settings.

GET /api/v2/device/:deviceID/routes

devices:routes

The credential has access to read or modify subnet router settings, approve and revoke subnet routes, and approve and revoke exit nodes.

Endpoints from devices:routes:read

POST /api/v2/device/:deviceID/routes

devices\_invites:read

The credential has access to read device invites.

GET /api/v2/device/:deviceID/device-invites

GET /api/v2/device-invites/:deviceInviteID

devices\_invites

The credential has access to read or modify device invites.

Endpoints from device\_invites:read

GET /api/v2/device/:deviceID/device-invites

GET, DELETE /api/v2/device-invites/:deviceInviteID

api\_access\_tokens:read

The credential has access to read API access tokens.

GET /api/v2/tailnet/:tailnet/keys (for API access tokens)

GET /api/v2/tailnet/:tailnet/keys/:keyID (for API access tokens)

api\_access\_tokens

The credential has access to read or modify API access tokens.

Endpoints from api\_access\_tokens:read

DELETE /api/v2/tailnet/:tailnet/keys/:keyID (for API access tokens)

auth\_keys:read

The credential has access to read auth keys.

GET /api/v2/tailnet/:tailnet/keys (for auth keys)

GET /api/v2/tailnet/:tailnet/keys/:keyID (for auth keys)

auth\_keys

The credential has access to read or modify auth keys.

Endpoints from auth\_keys:read

POST /api/v2/tailnet/:tailnet/keys (for auth keys)

DELETE /api/v2/tailnet/:tailnet/keys/:keyID (for auth keys)

oauth\_keys:read

The credential has access to read OAuth credentials and keys.

GET /api/v2/tailnet/:tailnet/keys/:keyID (only OAuth credentials and OAuth keys)

oauth\_keys

The credential has access to read or modify OAuth credentials and keys.

Endpoints from oauth\_keys:read

DELETE /api/v2/tailnet/:tailnet/keys/:keyID (for OAuth credentials and OAuth keys)

federated\_keys:read

The credential has access to read federated identities and keys generated by federated identities.

GET /api/v2/tailnet/:tailnet/keys/:keyID (only federated identities and keys generated by federated identities)

federated\_keys

The credential has access to read or modify federated identities and keys generated by federated identities.

Endpoints from federated\_keys:read

DELETE /api/v2/tailnet/:tailnet/keys/:keyID (only federated identities and keys generated by federated identities)

webhooks:read

The credential has access to read webhooks.

GET /api/v2/tailnet/:tailnet/webhooks

GET /api/v2/webhooks/:endpointID

webhooks

The credential has access to read, modify, and test webhooks and to rotate webhook secrets.

Endpoints from webhooks:read

POST /api/v2/tailnet/:tailnet/webhooks

PATCH, DELETE /api/v2/webhooks/:endpointID

POST /api/v2/webhooks/:endpointID/test

POST /api/v2/webhooks/:endpointID/rotate

log\_streaming:read

The credential has access to read log streaming configurations and their status.

GET /api/v2/tailnet/:tailnet/logging/:logType/stream

GET /api/v2/tailnet/:tailnet/logging/:logType/status

log\_streaming

The credential has access to read or modify log streaming configurations and check their status.
device\_invites and policy\_file are required when configuring log streaming to a private endpoint.

Endpoints from logstreaming:read

PUT, DELETE /api/v2/tailnet/:tailnet/logging/:logType/stream

logs:configuration:read

The credential has access to read configuration audit logs.

GET /api/v2/tailnet/:tailnet/logging/configuration

logs:network:read

The credential has access to read network flow logs.

GET /api/v2/tailnet/:tailnet/logging/network

GET /api/v2/tailnet/:tailnet/settings

logs:network

The credential has access to read network flow logs and modify their settings.

Endpoints from logs:network:read

PATCH /api/v2/tailnet/:tailnet/settings (for network logging only)

account\_settings:read

The credential has access to read tailnet contacts.

GET /api/v2/tailnet/:tailnet/contacts

account\_settings

The credential has access to read or modify tailnet contacts, and to resend verification emails.

Endpoints from account\_settings:read

PATCH /api/v2/tailnet/:tailnet/contacts/:contactType

POST /api/v2/tailnet/:tailnet/contacts/:contactType/resend-verification-email

feature\_settings:read

The credential has access to read posture integrations and tailnet feature settings.

GET /api/v2/tailnet/:tailnet/posture/integrations

GET /api/v2/posture/integrations/:integrationID

GET /api/v2/tailnet/:tailnet/settings

feature\_settings

The credential has access to read or modify posture integrations and tailnet feature settings.

Endpoints from feature\_settings:read

POST /api/v2/tailnet/:tailnet/posture/integrations

PATCH, DELETE /api/v2/posture/integrations/:integrationID

PATCH /api/v2/tailnet/:tailnet/settings

When new Tailscale functionality is provided, we will add it to existing scopes where applicable. That means a scope is not restricted to only access of APIs that existed at the time the credential was initially authorized—a scope will contain additional access where it makes sense for new or updated functionality.

You can find [documentation for the Tailscale API on our website][co-api]

## Revoke a trust credential

1. Open the [Trust credentials](https://login.tailscale.com/admin/settings/trust-credentials) page of the admin console.

2. Find the credential that you want to delete and select **Revoke**.

3. Select **Revoke** to confirm you want to revoke the credential.

When you revoke a trust credential, any active API access tokens that the credential created are also revoked.

## Audit logging of API access token creation

In [configuration audit logging][kb-audit-logging], creating an access token records the action in your audit log. The log entry shows the trust credential's Client ID as the actor. It also includes the time when the API access token was created.

If you believe your trust credential has been compromised, [revoke the trust credential][ar-revoke-a-trust-credential] (and set up a new credential when you're ready). Review the configuration audit logs to check whether and how the credential and API access tokens were used during the period of compromise.

## Legacy scopes

> **Note:**
>
> As of November 14, 2024 new trust credentials will use the scopes listed in the [scopes section][ar-scopes]. Existing trust credentials using the below scopes, and keys generated using these credentials, are still valid.

Scopes define the permissions granted to API access tokens created by your credential application.

You can use the following scopes in Tailscale trust credentials:

Scope ID
Description
Allowed endpoints

all
The credential has complete access to the tailnet. This scope is not restricted to only access of APIs that existed at the time the credential was initially authorized—the all scope also grants access to new APIs created in the future. The all and all:read scopes are the only scopes which can get a list of all access tokens which exist in the tailnet.

All endpoints, even endpoints which did not exist when the credential was initially authorized.
/api/v2/tailnet/:tailnet/keys/:keyID (for any key, not just itself)

all:read
The credential has read-only access to the tailnet. This scope is not restricted to only read access of APIs that existed at the time the credential was initially authorized—the all:read scope also grants read access to new APIs created in the future. The all and all:read scopes are the only scopes which can get a list of all access tokens which exist in the tailnet.

All endpoints, even endpoints which did not exist when the credential was initially authorized.
/api/v2/tailnet/:tailnet/keys/:keyID (for any key, not just itself)

acl

The credential has access to read and modify the tailnet policy file.

/api/v2/tailnet/:tailnet/devices

/api/v2/tailnet/:tailnet/acl

/api/v2/tailnet/:tailnet/acl/preview

/api/v2/tailnet/:tailnet/acl/validate

/api/v2/tailnet/:tailnet/keys/:keyID (for itself only)

/api/v2/device/:deviceID/attributes

/api/v2/device/:deviceID/attributes/:attributeKey

acl:read

The credential has access to read and validate the tailnet policy file.

/api/v2/tailnet/:tailnet/devices

/api/v2/tailnet/:tailnet/acl

/api/v2/tailnet/:tailnet/acl/preview

/api/v2/tailnet/:tailnet/acl/validate

/api/v2/tailnet/:tailnet/keys/:keyID (for itself only)

/api/v2/device/:deviceID/attributes

devices

The credential has access to read the list of devices in the tailnet, authorize or remove machines, create auth keys, and manipulate tags and attributes on
devices. You must select one or more tags when you create a credential with the devices scope. Auth keys created with this credential must have
those exact tags, or tags owned by the credential's tags

/api/v2/tailnet/:tailnet/devices

/api/v2/device/:deviceID

/api/v2/device/:deviceID/attributes

/api/v2/device/:deviceID/attributes/:attributeKey

/api/v2/device/:deviceID/authorized

/api/v2/device/:deviceID/key

/api/v2/device/:deviceID/tags

/api/v2/tailnet/:tailnet/keys (only auth keys, not access tokens)

/api/v2/tailnet/:tailnet/keys/\* (only auth keys, not access tokens)

/api/v2/tailnet/:tailnet/keys/:keyID (for itself only)

devices:read

The credential has access to read the list of devices, auth keys, attributes, and tags in the tailnet.

/api/v2/tailnet/:tailnet/devices

/api/v2/device/:deviceID

/api/v2/device/:deviceID/attributes

/api/v2/device/:deviceID/key

/api/v2/device/:deviceID/tags

/api/v2/tailnet/:tailnet/keys (only auth keys, not access tokens)

/api/v2/tailnet/:tailnet/keys/\* (only auth keys, not access tokens)

/api/v2/tailnet/:tailnet/keys/:keyID (for itself only)

dns

The credential has access to read and manipulate DNS settings.

/api/v2/tailnet/:tailnet/dns/\*

/api/v2/tailnet/:tailnet/keys/:keyID (for itself only)

dns:read

The credential has access to read DNS settings.

/api/v2/tailnet/:tailnet/dns/\*

/api/v2/tailnet/:tailnet/keys/:keyID (for itself only)

routes

The credential has access to read or modify subnet router settings, approve and revoke subnet routes, and approve and revoke exit nodes.

/api/v2/tailnet/:tailnet/devices

/api/v2/device/:deviceID/routes

/api/v2/tailnet/:tailnet/keys/:keyID (for itself only)

routes:read

The credential has access to read subnet router settings and exit node settings.

/api/v2/tailnet/:tailnet/devices

/api/v2/device/:deviceID/routes

/api/v2/tailnet/:tailnet/keys/:keyID (for itself only)

logs:read

The credential has access to read configuration audit logs.

/api/v2/tailnet/:tailnet/logs

/api/v2/tailnet/:tailnet/keys/:keyID (for itself only)

network-logs:read
The credential has access to read network flow logs.

/api/v2/tailnet/:tailnet/network-logs
/api/v2/tailnet/:tailnet/keys/:keyID (for itself only)

### Legacy scope equivalents

The following table maps legacy scope IDs to the newer equivalents.

| Legacy scope ID                                          | New scope ID                 |
| -------------------------------------------------------- | ---------------------------- |
| `devices` (for creating authentication keys)             | `auth_keys`                  |
| `devices` (for device posture attributes)                | `devices:posture_attributes` |
| `devices` (for managing device lifecycle and properties) | `devices:core`               |
| `routes`                                                 | `devices:routes`             |
| `acl`                                                    | `policy_file`                |
| `logs`                                                   | `logs:configuration`         |
| `network-logs`                                           | `logs:network`               |

[ar-revoke-a-trust-credential]: #revoke-a-trust-credential

[ar-scopes]: #scopes

[ar-legacy-scopes]: #legacy-scopes

[co-api]: /api

[kb-api]: /docs/reference/tailscale-api

[kb-audit-logging]: /docs/features/logging/audit-logging

[kb-oauth-clients]: /docs/features/oauth-clients

[kb-workload-identity]: /docs/features/workload-identity-federation

[ln-principle-of-least-privilege]: /learn/principle-of-least-privilege