{"slug":"oauth-clients","title":"OAuth clients","tags":["tailscale","auth"],"agent_summary":"Last validated: Jan 5, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# OAuth clients\r\n\r\nLast validated: Jan 5, 2026\r\n\r\nOAuth clients allow for ongoing access to the [Tailscale API](https://tailscale.com/docs/reference/tailscale-api) using the [client credentials flow](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.4) of the [OAuth 2.0 protocol](https://www.rfc-editor.org/rfc/rfc6749.html).\r\n\r\n## [How it works](https://tailscale.com/docs/features/oauth-clients\\#how-it-works)\r\n\r\nYou create an OAuth client that defines the [scopes](https://tailscale.com/docs/reference/trust-credentials#scopes) to allow when your client application uses the Tailscale API. An example scope is `dns:read`, which grants read-only access to a tailnet's DNS settings. Another example is the `devices:core` scope, which grants access to read and write the list of devices in the tailnet, authorize or remove machines, and manipulate tags on devices.\r\n\r\nTailscale restricts scopes to only the necessary Tailscale API endpoints needed for an operation. For example, tokens with the `dns:read` scope can access only the following Tailscale API endpoints:\r\n\r\n- `GET /api/v2/tailnet/:tailnet/dns/nameservers`\r\n- `GET /api/v2/tailnet/:tailnet/dns/preferences`\r\n- `GET /api/v2/tailnet/:tailnet/dns/searchpaths`\r\n- `GET /api/v2/tailnet/:tailnet/keys/:keyID` (for itself only)\r\n\r\nAn OAuth client consists of a client ID and a client secret. When you create an OAuth client, Tailscale creates these for you. Within your client application, use the client ID and client secret to request an API access token from the [Tailscale OAuth token endpoint](https://tailscale.com/docs/features/oauth-clients#tailscale-oauth-token-endpoint). You use the access token to make calls to the Tailscale API. The access token grants permission only for the scopes that you defined when you created the OAuth client.\r\n\r\nAn API access token expires after one hour. For continuous access, shortly before an API access token expires, request a new API access token from the Tailscale OAuth token endpoint.\r\n\r\nOAuth client libraries in popular programming languages can handle the API access token generation and renewal.\r\n\r\nThe Tailscale OAuth implementation uses the [OAuth 2.0 protocol](https://www.rfc-editor.org/rfc/rfc6749.html).\r\n\r\n## [Prerequisites](https://tailscale.com/docs/features/oauth-clients\\#prerequisites)\r\n\r\nYou need to be an [Owner, Admin, Network admin, or IT admin](https://tailscale.com/docs/reference/user-roles) of a tailnet to create, revoke, or delete OAuth clients.\r\n\r\nOwners and Admins can create an OAuth client with any scope and any [tag](https://tailscale.com/docs/features/tags) that is in the tailnet. Other users can create an OAuth client with only the scopes and tags for which they have permissions. For example, a Network admin cannot grant the `devices:core` scope, but an IT admin can.\r\n\r\n## [Setting up an OAuth client](https://tailscale.com/docs/features/oauth-clients\\#setting-up-an-oauth-client)\r\n\r\n1. Open the [Trust credentials](https://login.tailscale.com/admin/settings/trust-credentials) page of the admin console.\r\n\r\n2. Select the **Credential** button.\r\n\r\n3. Select **OAuth**.\r\n\r\n4. Select the set of operations that can be performed with tokens created by the new OAuth client. For a given operation, select **Read** or **Write**. For a description of the operations, refer to [Scopes](https://tailscale.com/docs/reference/trust-credentials#scopes).\r\n\r\n5. Select **Generate credential**.\r\n\r\n6. In the **Credential created** page, you can access the new OAuth client's ID and secret. Copy both the client ID and secret, as you need them for your client code. Note that after you close the **Credential created** page, you won't be able to copy the secret again.\r\n\r\n\r\n\r\nStore the client secret securely.\r\n\r\n\r\n![The 'Generate OAuth client' page in the admin console](https://tailscale.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fgenerated-oauth-client.6e110b27.jpg&w=750&q=75)\r\n7. Select **Done**.\r\n\r\nYour OAuth client is now configured. Use the client ID and secret when you configure your OAuth client application. Note that Tailscale-generated OAuth client secrets are case-sensitive.\r\n\r\n\r\nIf a user creates an OAuth client, the OAuth client will continue to function and generate API access tokens even if the user no longer has access to the tailnet. Admins can access all configured OAuth clients in the [Trust credentials](https://login.tailscale.com/admin/settings/trust-credentials) page of the admin console.\r\n\r\n## [Tailscale OAuth token endpoint](https://tailscale.com/docs/features/oauth-clients\\#tailscale-oauth-token-endpoint)\r\n\r\nThe Tailscale OAuth token endpoint is `https://api.tailscale.com/api/v2/oauth/token`.\r\n\r\nMake requests to the Tailscale OAuth token endpoint when you need an API access token. The Tailscale OAuth token endpoint accepts requests that conform to the OAuth 2.0 client credentials grant [request format](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.4.2), and returns responses that conform to the OAuth 2.0 client credentials grant [response format](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.4.3).\r\n\r\nRequests to the OAuth token endpoint can include `scope` and `tags` request parameters, which specify space-delimited lists of requested scopes and [tags](https://tailscale.com/docs/features/tags), respectively. The OAuth client must have permission to grant the requested scopes and tags. For example, an OAuth client with the `all` scope (which grants all other scopes as well as all device tags) can request an access token with the `devices:core` scope and the `tag:server` tag.\r\n\r\nTags are only relevant for tokens with the `devices:core`, `auth_keys`, or `all` scopes. The OAuth client ignores tags if none of these scopes are present. The `tags` parameter is not part of the OAuth 2.0 specification, and not all clients might support it.\r\n\r\n## [OAuth client libraries](https://tailscale.com/docs/features/oauth-clients\\#oauth-client-libraries)\r\n\r\nPopular programming languages provide OAuth client libraries for using OAuth clients. Here are several:\r\n\r\n- Go: `clientcredentials` [Visit page →](https://pkg.go.dev/golang.org/x/oauth2/clientcredentials)\r\n- Node: `OAuth2` [Visit page →](https://github.com/ciaranj/node-oauth#oauth20)\r\n- PHP: `ClientCredentials.php` [Visit page →](https://github.com/thephpleague/oauth2-client/blob/master/src/Grant/ClientCredentials.php)\r\n- Ruby: `client_credentials.rb` [Visit page →](https://gitlab.com/oauth-xx/oauth2/blob/main/lib/oauth2/strategy/client_credentials.rb)\r\n- Rust: `Client Credentials Grant` [Visit page →](https://docs.rs/oauth2/latest/oauth2/#client-credentials-grant)\r\n\r\nFor example, the following Go code shows how to create an OAuth client object that uses your client ID and client secret to generate an API access token for calls to the Tailscale API:\r\n\r\n```go\r\npackage main\r\n\r\nimport (\r\n \"context\"\r\n \"fmt\"\r\n \"io/ioutil\"\r\n \"log\"\r\n \"os\"\r\n\r\n \"golang.org/x/oauth2/clientcredentials\"\r\n)\r\n\r\nfunc main() {\r\n var oauthConfig = &clientcredentials.Config{\r\n ClientID: os.Getenv(\"OAUTH_CLIENT_ID\"),\r\n ClientSecret: os.Getenv(\"OAUTH_CLIENT_SECRET\"),\r\n TokenURL: \"https://api.tailscale.com/api/v2/oauth/token\",\r\n }\r\n\r\n client := oauthConfig.Client(context.Background())\r\n // Replace example.com with your tailnet ID.\r\n resp, err := client.Get(\"https://api.tailscale.com/api/v2/tailnet/example.com/devices\")\r\n if err != nil {\r\n log.Fatalf(\"error getting keys: %v\", err)\r\n }\r\n\r\n body, err := ioutil.ReadAll(resp.Body)\r\n if err != nil {\r\n log.Fatalf(\"error reading response body: %v\", err)\r\n }\r\n\r\n fmt.Printf(\"response: %s\", string(body))\r\n}\r\n```\r\n\r\nThe example requires that you define environment variables `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET`, with their values set to the **Client ID** and **Client secret** that you create when you [set up an OAuth client](https://tailscale.com/docs/features/oauth-clients#setting-up-an-oauth-client).\r\n\r\n## [Verifying you can generate API access tokens](https://tailscale.com/docs/features/oauth-clients\\#verifying-you-can-generate-api-access-tokens)\r\n\r\nAfter you [set up an OAuth client](https://tailscale.com/docs/features/oauth-clients#setting-up-an-oauth-client), you can confirm that you can generate API access tokens by making a `curl` request to the [Tailscale OAuth token endpoint](https://tailscale.com/docs/features/oauth-clients#tailscale-oauth-token-endpoint).\r\n\r\n```shell\r\n curl -d \"client_id=${OAUTH_CLIENT_ID}\" -d \"client_secret=${OAUTH_CLIENT_SECRET}\" \\\r\n \"https://api.tailscale.com/api/v2/oauth/token\"\r\n```\r\n\r\nThe example requires that you define environment variables `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET`, with their values set to your **Client ID** and **Client secret**.\r\n\r\nHere's an example response showing the API access token:\r\n\r\n```json\r\n{\"access_token\":\"tskey-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ\",\"token_type\":\"Bearer\",\"expires_in\":3600,\"scope\":\"devices\"}\r\n```\r\n\r\n## [Generating long-lived auth keys](https://tailscale.com/docs/features/oauth-clients\\#generating-long-lived-auth-keys)\r\n\r\nYou cannot generate long-lived [auth keys](https://tailscale.com/docs/features/access-control/auth-keys), because they expire after 90 days, or, for one-off keys, as soon as you use them.\r\n\r\nInstead of a long-lived auth key, you can generate an OAuth client with the `auth_keys` scope. Use the OAuth client to generate new auth keys as needed, by making a `POST` request to the [`/api/v2/tailnet/:tailnet/keys`](https://tailscale.com/api#tag/devices/POST/device/%7BdeviceId%7D/key) API method. When you create an OAuth client with the scope `auth_keys`, you must select one or more [tags](https://tailscale.com/docs/features/tags), which can be any tag or set of tags in your tailnet. You must also specify these tags in the API call.\r\n\r\nFor example, to assign your device a specific tag, such as `tag:server`, create an OAuth client with `tag:server`. When you create the auth key, specify `tag:server` as the tag for the auth key.\r\n\r\nAlternatively, if you need an OAuth client that supports more than one tag, set up [tag ownership](https://tailscale.com/docs/features/tags#ownership). For example, to tag some devices with `tag:server` and others with `tag:database`:\r\n\r\n1. Set up a tag owner `tag:terraform-tag-owner` for both `tag:server` and `tag:database`:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```json\r\n{\r\n \"tagOwners\": {\r\n \"tag:terraform-tag-owner\": [\"\"],\r\n \"tag:server\": [\"tag:terraform-tag-owner\"],\r\n \"tag:database\": [\"tag:terraform-tag-owner\"],\r\n },\r\n}\r\n```\r\n\r\n2. Create an OAuth client with tag `tag:terraform-tag-owner`.\r\n\r\n3. Create an auth key from that OAuth client, and specify either `tag:server` or `tag:database` as the tag for the auth key.\r\n\r\n\r\n## [Shorthand notation for tailnet ID](https://tailscale.com/docs/features/oauth-clients\\#shorthand-notation-for-tailnet-id)\r\n\r\nWhen you use an access token to make an API call, you can optionally use the value `-` as the [tailnet ID](https://tailscale.com/docs/concepts/tailnet-name#tailnet-id). You can find your tailnet ID in the [General](https://login.tailscale.com/admin/settings/general) page of the admin console. You do not need to specify the tailnet ID.\r\n\r\nFor example, this command:\r\n\r\n```shell\r\ncurl -u $ACCESS_TOKEN: \"https://api.tailscale.com/api/v2/tailnet/example.com/devices\"\r\n```\r\n\r\nis equivalent to:\r\n\r\n```shell\r\ncurl -u $ACCESS_TOKEN: \"https://api.tailscale.com/api/v2/tailnet/-/devices\"\r\n```\r\n\r\nas long as the access token is owned by the `example.com` tailnet.\r\n\r\nYou can also include the access token in the request header by using the `-H` option:\r\n\r\n```shell\r\ncurl -H \"Authorization: Bearer $ACCESS_TOKEN\" \"https://api.tailscale.com/api/v2/tailnet/-/devices\"\r\n```\r\n\r\n## [Register new nodes using OAuth credentials](https://tailscale.com/docs/features/oauth-clients\\#register-new-nodes-using-oauth-credentials)\r\n\r\nYou can use an OAuth secret directly in [`tailscale up`](https://tailscale.com/docs/reference/tailscale-cli/up) to register a new node:\r\n\r\n```shell\r\ntailscale up --auth-key=${OAUTH_CLIENT_SECRET} --advertise-tags=tag:ci\r\n```\r\n\r\nThe OAuth client must have the `auth_keys` scope. When you [create a client](https://tailscale.com/docs/features/oauth-clients#setting-up-an-oauth-client) with the `auth_keys` scope, you assign one or more [tags](https://tailscale.com/docs/features/tags) for the scope. You must pass in one or more of those tags to the `--advertise-tags` flag.\r\n\r\nThe `--auth-key` flag can accept additional URL-style parameters when used with OAuth secrets:\r\n\r\n```shell\r\ntailscale up --auth-key='${OAUTH_CLIENT_SECRET}?ephemeral=false&preauthorized=true' --advertise-tags=tag:ci\r\n```\r\n\r\nThe available parameters are:\r\n\r\n- `ephemeral`: register as an [ephemeral node](https://tailscale.com/docs/features/ephemeral-nodes) (defaults to `true`)\r\n- `preauthorized`: skip manual [device approval](https://tailscale.com/docs/features/access-control/device-management/device-approval) (defaults to `false`)\r\n- `baseURL`: base URL for the Tailscale API (defaults to `https://api.tailscale.com`)\r\n\r\n## [get-authkey utility](https://tailscale.com/docs/features/oauth-clients\\#get-authkey-utility)\r\n\r\nThe `get-authkey` utility returns a new auth key to `stdout`, based on environment variables that contain values for your OAuth client ID and secret. Use `get-authkey` to generate auth keys for scripts or other automation.\r\n\r\nAll auth keys created from an OAuth client must use [tags](https://tailscale.com/docs/features/tags). You can optionally pass in arguments to `get-authkey` to specify whether the [key type](https://tailscale.com/docs/features/access-control/auth-keys#types-of-auth-keys) is ephemeral, reusable, and/or pre-authorized.\r\n\r\n`get-authkey` requires Go 1.23 or later.\r\n\r\nTo build and run `get-authkey` directly:\r\n\r\n1. Set the following environment variables:\r\n\r\n\r\n - `TS_API_CLIENT_ID`: The OAuth client ID for your tailnet.\r\n - `TS_API_CLIENT_SECRET`: The OAuth client secret for your tailnet.\r\n\r\n```shell\r\nexport TS_API_CLIENT_ID= TS_API_CLIENT_SECRET=\r\n```\r\n\r\n2. Run:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ngo run tailscale.com/cmd/get-authkey@latest -tags tag:development\r\n```\r\n\r\n\r\nYou can pass in the following parameters:\r\n\r\n- `-tags`: Required. Apply the comma-separated list of tags to the auth key.\r\n- `-reusable` (Optional): Allocate a reusable auth key. If not set, defaults to false.\r\n- `-ephemeral` (Optional): Allocate an ephemeral auth key. If not set, defaults to false.\r\n- `-preauth` (Optional): Allocate the auth key as pre-authorized. If not set, defaults to true.\r\n\r\nFor example:\r\n\r\n```shell\r\ngo run tailscale.com/cmd/get-authkey@latest -reusable -tags tag:development\r\n```\r\n\r\nAs an alternative, you can download the `get-authkey` source code and run it from a local repository:\r\n\r\n1. Clone the [`tailscale/tailscale`](https://github.com/tailscale/tailscale) repository.\r\n\r\n2. Open a command prompt and change directories to the root of the local `tailscale/` folder.\r\n\r\n3. Run `get-authkey`:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ngo run ./cmd/get-authkey/main.go -tags tag:development\r\n```\r\n\r\n\r\n## [Scopes](https://tailscale.com/docs/features/oauth-clients\\#scopes)\r\n\r\nInformation about our scopes has moved to the [trust credentials](https://tailscale.com/docs/reference/trust-credentials#scopes) topic.\r\n\r\n## [Legacy scopes](https://tailscale.com/docs/features/oauth-clients\\#legacy-scopes)\r\n\r\nInformation about our legacy scopes has moved to the [trust credentials](https://tailscale.com/docs/reference/trust-credentials#legacy-scopes) topic.\r\n\r\n## [Limitations](https://tailscale.com/docs/features/oauth-clients\\#limitations)\r\n\r\n- OAuth clients must be owned by the tailnet, and not by an individual user.\r\n- An OAuth access token expires after 1 hour—this time cannot be modified.\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

OAuth clients

\n

Last validated: Jan 5, 2026

\n

OAuth clients allow for ongoing access to the Tailscale API using the client credentials flow of the OAuth 2.0 protocol.

\n

How it works

\n

You create an OAuth client that defines the scopes to allow when your client application uses the Tailscale API. An example scope is dns:read, which grants read-only access to a tailnet's DNS settings. Another example is the devices:core scope, which grants access to read and write the list of devices in the tailnet, authorize or remove machines, and manipulate tags on devices.

\n

Tailscale restricts scopes to only the necessary Tailscale API endpoints needed for an operation. For example, tokens with the dns:read scope can access only the following Tailscale API endpoints:

\n
    \n
  • GET /api/v2/tailnet/:tailnet/dns/nameservers
    • \n
  • GET /api/v2/tailnet/:tailnet/dns/preferences
    • \n
  • GET /api/v2/tailnet/:tailnet/dns/searchpaths
    • \n
  • GET /api/v2/tailnet/:tailnet/keys/:keyID (for itself only)
    • \n
\n

An OAuth client consists of a client ID and a client secret. When you create an OAuth client, Tailscale creates these for you. Within your client application, use the client ID and client secret to request an API access token from the Tailscale OAuth token endpoint. You use the access token to make calls to the Tailscale API. The access token grants permission only for the scopes that you defined when you created the OAuth client.

\n

An API access token expires after one hour. For continuous access, shortly before an API access token expires, request a new API access token from the Tailscale OAuth token endpoint.

\n

OAuth client libraries in popular programming languages can handle the API access token generation and renewal.

\n

The Tailscale OAuth implementation uses the OAuth 2.0 protocol.

\n

Prerequisites

\n

You need to be an Owner, Admin, Network admin, or IT admin of a tailnet to create, revoke, or delete OAuth clients.

\n

Owners and Admins can create an OAuth client with any scope and any tag that is in the tailnet. Other users can create an OAuth client with only the scopes and tags for which they have permissions. For example, a Network admin cannot grant the devices:core scope, but an IT admin can.

\n

Setting up an OAuth client

\n
    \n
  1. \n

    Open the Trust credentials page of the admin console.

    \n
    2. \n
  2. \n

    Select the Credential button.

    \n
    3. \n
  3. \n

    Select OAuth.

    \n
    4. \n
  4. \n

    Select the set of operations that can be performed with tokens created by the new OAuth client. For a given operation, select Read or Write. For a description of the operations, refer to Scopes.

    \n
    5. \n
  5. \n

    Select Generate credential.

    \n
    6. \n
  6. \n

    In the Credential created page, you can access the new OAuth client's ID and secret. Copy both the client ID and secret, as you need them for your client code. Note that after you close the Credential created page, you won't be able to copy the secret again.

    \n
    7. \n
\n

Store the client secret securely.

\n

\"The\r\n7. Select Done.

\n

Your OAuth client is now configured. Use the client ID and secret when you configure your OAuth client application. Note that Tailscale-generated OAuth client secrets are case-sensitive.

\n

If a user creates an OAuth client, the OAuth client will continue to function and generate API access tokens even if the user no longer has access to the tailnet. Admins can access all configured OAuth clients in the Trust credentials page of the admin console.

\n

Tailscale OAuth token endpoint

\n

The Tailscale OAuth token endpoint is https://api.tailscale.com/api/v2/oauth/token.

\n

Make requests to the Tailscale OAuth token endpoint when you need an API access token. The Tailscale OAuth token endpoint accepts requests that conform to the OAuth 2.0 client credentials grant request format, and returns responses that conform to the OAuth 2.0 client credentials grant response format.

\n

Requests to the OAuth token endpoint can include scope and tags request parameters, which specify space-delimited lists of requested scopes and tags, respectively. The OAuth client must have permission to grant the requested scopes and tags. For example, an OAuth client with the all scope (which grants all other scopes as well as all device tags) can request an access token with the devices:core scope and the tag:server tag.

\n

Tags are only relevant for tokens with the devices:core, auth_keys, or all scopes. The OAuth client ignores tags if none of these scopes are present. The tags parameter is not part of the OAuth 2.0 specification, and not all clients might support it.

\n

OAuth client libraries

\n

Popular programming languages provide OAuth client libraries for using OAuth clients. Here are several:

\n\n

For example, the following Go code shows how to create an OAuth client object that uses your client ID and client secret to generate an API access token for calls to the Tailscale API:

\n
package main\r\n\r\nimport (\r\n        \"context\"\r\n        \"fmt\"\r\n        \"io/ioutil\"\r\n        \"log\"\r\n        \"os\"\r\n\r\n        \"golang.org/x/oauth2/clientcredentials\"\r\n)\r\n\r\nfunc main() {\r\n        var oauthConfig = &clientcredentials.Config{\r\n                ClientID:     os.Getenv(\"OAUTH_CLIENT_ID\"),\r\n                ClientSecret: os.Getenv(\"OAUTH_CLIENT_SECRET\"),\r\n                TokenURL:     \"https://api.tailscale.com/api/v2/oauth/token\",\r\n        }\r\n\r\n        client := oauthConfig.Client(context.Background())\r\n        // Replace example.com with your tailnet ID.\r\n        resp, err := client.Get(\"https://api.tailscale.com/api/v2/tailnet/example.com/devices\")\r\n        if err != nil {\r\n                log.Fatalf(\"error getting keys: %v\", err)\r\n        }\r\n\r\n        body, err := ioutil.ReadAll(resp.Body)\r\n        if err != nil {\r\n                log.Fatalf(\"error reading response body: %v\", err)\r\n        }\r\n\r\n        fmt.Printf(\"response: %s\", string(body))\r\n}\n
\n

The example requires that you define environment variables OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET, with their values set to the Client ID and Client secret that you create when you set up an OAuth client.

\n

Verifying you can generate API access tokens

\n

After you set up an OAuth client, you can confirm that you can generate API access tokens by making a curl request to the Tailscale OAuth token endpoint.

\n
 curl -d \"client_id=${OAUTH_CLIENT_ID}\" -d \"client_secret=${OAUTH_CLIENT_SECRET}\" \\\r\n     \"https://api.tailscale.com/api/v2/oauth/token\"\n
\n

The example requires that you define environment variables OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET, with their values set to your Client ID and Client secret.

\n

Here's an example response showing the API access token:

\n
{\"access_token\":\"tskey-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ\",\"token_type\":\"Bearer\",\"expires_in\":3600,\"scope\":\"devices\"}\n
\n

Generating long-lived auth keys

\n

You cannot generate long-lived auth keys, because they expire after 90 days, or, for one-off keys, as soon as you use them.

\n

Instead of a long-lived auth key, you can generate an OAuth client with the auth_keys scope. Use the OAuth client to generate new auth keys as needed, by making a POST request to the /api/v2/tailnet/:tailnet/keys API method. When you create an OAuth client with the scope auth_keys, you must select one or more tags, which can be any tag or set of tags in your tailnet. You must also specify these tags in the API call.

\n

For example, to assign your device a specific tag, such as tag:server, create an OAuth client with tag:server. When you create the auth key, specify tag:server as the tag for the auth key.

\n

Alternatively, if you need an OAuth client that supports more than one tag, set up tag ownership. For example, to tag some devices with tag:server and others with tag:database:

\n
    \n
  1. Set up a tag owner tag:terraform-tag-owner for both tag:server and tag:database:
    2. \n
\n
{\r\n     \"tagOwners\": {\r\n       \"tag:terraform-tag-owner\": [\"<your-email-address>\"],\r\n       \"tag:server\": [\"tag:terraform-tag-owner\"],\r\n       \"tag:database\": [\"tag:terraform-tag-owner\"],\r\n     },\r\n}\n
\n
    \n
  1. \n

    Create an OAuth client with tag tag:terraform-tag-owner.

    \n
    2. \n
  2. \n

    Create an auth key from that OAuth client, and specify either tag:server or tag:database as the tag for the auth key.

    \n
    3. \n
\n

Shorthand notation for tailnet ID

\n

When you use an access token to make an API call, you can optionally use the value - as the tailnet ID. You can find your tailnet ID in the General page of the admin console. You do not need to specify the tailnet ID.

\n

For example, this command:

\n
curl -u $ACCESS_TOKEN: \"https://api.tailscale.com/api/v2/tailnet/example.com/devices\"\n
\n

is equivalent to:

\n
curl -u $ACCESS_TOKEN: \"https://api.tailscale.com/api/v2/tailnet/-/devices\"\n
\n

as long as the access token is owned by the example.com tailnet.

\n

You can also include the access token in the request header by using the -H option:

\n
curl -H \"Authorization: Bearer $ACCESS_TOKEN\" \"https://api.tailscale.com/api/v2/tailnet/-/devices\"\n
\n

Register new nodes using OAuth credentials

\n

You can use an OAuth secret directly in tailscale up to register a new node:

\n
tailscale up --auth-key=${OAUTH_CLIENT_SECRET} --advertise-tags=tag:ci\n
\n

The OAuth client must have the auth_keys scope. When you create a client with the auth_keys scope, you assign one or more tags for the scope. You must pass in one or more of those tags to the --advertise-tags flag.

\n

The --auth-key flag can accept additional URL-style parameters when used with OAuth secrets:

\n
tailscale up --auth-key='${OAUTH_CLIENT_SECRET}?ephemeral=false&preauthorized=true' --advertise-tags=tag:ci\n
\n

The available parameters are:

\n
    \n
  • ephemeral: register as an ephemeral node (defaults to true)
    • \n
  • preauthorized: skip manual device approval (defaults to false)
    • \n
  • baseURL: base URL for the Tailscale API (defaults to https://api.tailscale.com)
    • \n
\n

get-authkey utility

\n

The get-authkey utility returns a new auth key to stdout, based on environment variables that contain values for your OAuth client ID and secret. Use get-authkey to generate auth keys for scripts or other automation.

\n

All auth keys created from an OAuth client must use tags. You can optionally pass in arguments to get-authkey to specify whether the key type is ephemeral, reusable, and/or pre-authorized.

\n

get-authkey requires Go 1.23 or later.

\n

To build and run get-authkey directly:

\n
    \n
  1. \n

    Set the following environment variables:

    \n
      \n
    • TS_API_CLIENT_ID: The OAuth client ID for your tailnet.
      • \n
    • TS_API_CLIENT_SECRET: The OAuth client secret for your tailnet.
      • \n
    \n
    2. \n
\n
export TS_API_CLIENT_ID=<clientID> TS_API_CLIENT_SECRET=<secret>\n
\n
    \n
  1. Run:
    2. \n
\n
go run tailscale.com/cmd/get-authkey@latest -tags tag:development\n
\n

You can pass in the following parameters:

\n
    \n
  • -tags: Required. Apply the comma-separated list of tags to the auth key.
    • \n
  • -reusable (Optional): Allocate a reusable auth key. If not set, defaults to false.
    • \n
  • -ephemeral (Optional): Allocate an ephemeral auth key. If not set, defaults to false.
    • \n
  • -preauth (Optional): Allocate the auth key as pre-authorized. If not set, defaults to true.
    • \n
\n

For example:

\n
go run tailscale.com/cmd/get-authkey@latest -reusable -tags tag:development\n
\n

As an alternative, you can download the get-authkey source code and run it from a local repository:

\n
    \n
  1. \n

    Clone the tailscale/tailscale repository.

    \n
    2. \n
  2. \n

    Open a command prompt and change directories to the root of the local tailscale/ folder.

    \n
    3. \n
  3. \n

    Run get-authkey:

    \n
    4. \n
\n
go run ./cmd/get-authkey/main.go -tags tag:development\n
\n

Scopes

\n

Information about our scopes has moved to the trust credentials topic.

\n

Legacy scopes

\n

Information about our legacy scopes has moved to the trust credentials topic.

\n

Limitations

\n
    \n
  • OAuth clients must be owned by the tailnet, and not by an individual user.
    • \n
  • An OAuth access token expires after 1 hour—this time cannot be modified.
    • \n
\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}