Trust credentials
Trust credentials provide a framework for delegated and scoped access to the Tailscale 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 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 and OIDC workload identities. Information common to both forms is shared below.
Scopes
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.
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 | 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. |
|
dns:read | The credential has access to read DNS settings. |
|
dns | The credential has access to read and manipulate DNS settings. |
|
policy_file:read | The credential has access to read and validate the tailnet policy file.
|
|
policy_file | The credential has access to read, validate, and modify the tailnet policy file.
|
|
users:read | The credential has access to read user information. |
|
users | The credential has access to read user information, modify user roles, and handle user approval, suspension, deletion, and restoration. |
|
devices:core:read | The credential has access to read devices in the tailnet. |
|
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:posture_attributes:read | The credential has access to read device posture attributes. |
|
devices:posture_attributes | The credential has access to manipulate and read device posture attributes. |
|
devices:routes:read | The credential has access to read subnet router settings and exit node settings. |
|
devices:routes | The credential has access to read or modify subnet router settings, approve and revoke subnet routes, and approve and revoke exit nodes. |
|
devices_invites:read | The credential has access to read device invites. |
|
devices_invites | The credential has access to read or modify device invites. |
|
api_access_tokens:read | The credential has access to read API access tokens. |
|
api_access_tokens | The credential has access to read or modify API access tokens. |
|
auth_keys:read | The credential has access to read auth keys. |
|
auth_keys | The credential has access to read or modify auth keys. |
|
oauth_keys:read | The credential has access to read OAuth credentials and keys. |
|
oauth_keys | The credential has access to read or modify OAuth credentials and keys. |
|
webhooks:read | The credential has access to read webhooks. |
|
webhooks | The credential has access to read, modify, and test webhooks and to rotate webhook secrets. |
|
log_streaming:read | The credential has access to read log streaming configurations and their status. |
|
log_streaming | The credential has access to read or modify log streaming configurations and check their status.
|
|
logs:configuration:read | The credential has access to read configuration audit logs. |
|
logs:network:read | The credential has access to read network flow logs. |
|
logs:network | The credential has access to read network flow logs and modify their settings. |
|
account_settings:read | The credential has access to read tailnet contacts. |
|
account_settings | The credential has access to read or modify tailnet contacts, and to resend verification emails. |
|
feature_settings:read | The credential has access to read posture integrations and tailnet feature settings. |
|
feature_settings | The credential has access to read or modify posture integrations and tailnet feature 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
Revoke a trust credential
-
Open the Trust credentials page of the admin console.
-
Find the credential that you want to delete and select Revoke.
-
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, 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 (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
As of November 14, 2024 new trust credentials will use the scopes listed in the scopes section. 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: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. |
|
acl | The credential has access to read and modify the tailnet policy file. |
|
acl:read | The credential has access to read and validate the tailnet policy file. |
|
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:read | The credential has access to read the list of devices, auth keys, attributes, and tags in the tailnet. |
|
dns | The credential has access to read and manipulate DNS settings. |
|
dns:read | The credential has access to read DNS settings. |
|
routes | The credential has access to read or modify subnet router settings, approve and revoke subnet routes, and approve and revoke exit nodes. |
|
routes:read | The credential has access to read subnet router settings and exit node settings. |
|
logs:read | The credential has access to read configuration audit logs. |
|
network-logs:read | The credential has access to read network flow logs. |
|
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 |