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 federated OIDC workload identities (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
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. |
|
federated_keys:read | The credential has access to read 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. |
|
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. |
|