Skip to main content

ZeroTier API Tokens

Access to the ZeroTier APIs requires an authentication token. This guide describes the different types of tokens available and how to create and manage them.

Service Accounts and API Tokens​

note

Service Accounts and the New Central API are available to New Central customers on an Essential plan or above. For pricing information, see the Pricing page on our website.

Service accounts are neutral administrator accounts designed for API access and automation. They are not tied to any individual user's account, making them ideal for continuous integration, infrastructure-as-code deployments, and other automated workflows.

What are Service Accounts?​

Service accounts provide a dedicated identity for programmatic access to the New Central API. Key features include:

  • Independent from user accounts - Service accounts persist even when team members change
  • Administrator privileges - Currently, service accounts have blanket administrator access to the organization
  • Multiple API tokens - Each service account can have one or more API tokens
  • Customizable expiry - Set custom expiration dates for API tokens to enhance security
  • Centralized management - View and manage all service accounts from the Organization settings

For complete API documentation, see the New Central API Reference.

Creating a Service Account​

To create a service account in New Central:

  1. Navigate to your Organization
  2. Select the Service Accounts tab
  3. Click the Add Service Account button

Service Accounts Page

  1. Enter a Name and Description for the service account
  2. The service account will be automatically created and assigned a unique identifier in the format service-account@org-[orgid].ztsa

Generating API Tokens​

Each service account needs at least one API token to authenticate with the New Central API.

To create an API token:

  1. After creating the service account, you'll see the Assign API Tokens section
  2. Enter a Token name to identify the token's purpose
  3. Set an Expiration Date - Choose when this token should expire for enhanced security
  4. Click Generate API Token
Token Expiration

While you can set any expiration date, creating long-lasting tokens (e.g., years in the future) is a security risk. If a token is compromised, it remains valid until expiration or unless revoked. Best practice is to set shorter expiration periods and rotate tokens regularly.

Generate API Token

Important - Save Your Token

The API token is displayed only once upon creation. Copy and securely store the token before closing the dialog. You will not be able to view it again.

API Token Generated

Managing Service Accounts​

Service accounts appear in your Organization's Access Controls tab alongside regular user accounts, identified by their service account icon and email format.

Service Accounts in Access Controls

To manage an existing service account:

  1. Navigate to the Service Accounts tab
  2. Click the three-dot menu (⋮) in the Actions column for the service account

Available actions:

  • Edit Service Account - Update name, description, and manage API tokens
  • Manage Tokens - View, rename, and delete existing API tokens
  • Delete Service Account - Permanently remove the service account and revoke all associated tokens

Service Account Actions

Viewing and Managing Tokens​

When editing a service account, you can view all API tokens associated with it:

Edit Service Account Dialog

  • Token name - The descriptive name you assigned
  • Expiry Date - When the token will expire
  • Last Used - Timestamp of the token's most recent use
  • Actions - Edit or delete individual tokens
Best Practice

Rotate API tokens regularly by creating new tokens with expiry dates and deleting old ones. This limits the potential impact of a compromised token.

Using Service Account Tokens​

Service account API tokens work with the New Central API just like personal API tokens:

# List networks using a service account token
curl -X GET \
  -H "Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN" \
  https://api.zerotier.com/api/v1/network

See the New Central API Reference for complete API documentation.

Security Best Practices​

  • Use descriptive names - Clearly identify what each service account and token is used for
  • Set expiration dates - Don't create tokens that never expire
  • Rotate regularly - Create new tokens and delete old ones periodically
  • Limit scope - Create separate service accounts for different automation tasks when possible
  • Store securely - Use secret management tools (HashiCorp Vault, AWS Secrets Manager, etc.) to store tokens
  • Monitor usage - Check the "Last Used" timestamp to identify unused tokens that can be deleted