Tailscale Configuration

Cartography supports two ways to authenticate to the Tailscale API:

• OAuth client (recommended) — tag-scoped, not tied to a user, exchanged at sync time for a short-lived bearer token. Matches Tailscale’s recommended pattern for service integrations.

• API access token — long-lived, tied to a user account.

In both cases, pass --tailscale-org <tailnet-name> (find it under Settings → General). For self-hosted instances, set --tailscale-base-url (default https://api.tailscale.com/api/v2); the same base URL is used for the OAuth token endpoint.

OAuth client (recommended)

1. Create an OAuth client at Settings → OAuth clients with the read-only scopes cartography needs:

   • devices:core:read — /tailnet/:org/devices

   • devices:posture_attributes:read — /device/:id/attributes

   • users:read — /tailnet/:org/users

   • policy_file:read — /tailnet/:org/acl

   • feature_settings:read — /tailnet/:org/settings and /tailnet/:org/posture/integrations

   See trust credentials for the canonical scope list.

2. Put the client ID and secret in two environment variables and pass their names to cartography:

   export TS_OAUTH_CLIENT_ID="<client id>"
   export TS_OAUTH_CLIENT_SECRET="<client secret>"
   
   cartography \
     --tailscale-oauth-client-id-env-var TS_OAUTH_CLIENT_ID \
     --tailscale-oauth-client-secret-env-var TS_OAUTH_CLIENT_SECRET \
     --tailscale-org example.com
   

Cartography will exchange the credentials at {base_url}/oauth/token (RFC 6749 client_credentials grant) and use the returned access token for the rest of the sync.

API access token

1. Create an API access token at Settings → Keys.

2. Export it (e.g. TAILSCALE_TOKEN) and pass --tailscale-token-env-var TAILSCALE_TOKEN.

If both --tailscale-token-env-var and the OAuth client flags are set, the OAuth client is used and a warning is logged.