API Tokens

Secure tokens for API access and CI/CD deployments.

Overview

ZeroDeploy supports two types of API tokens:

Site Tokens

Site-scoped tokens that can only deploy and manage a specific site. Ideal for single-site CI/CD pipelines.

Org Tokens

Organization-scoped tokens that can deploy to any site within an org. Perfect for monorepos where one CI/CD pipeline deploys multiple sites.

Scope vs. Permissions

The token scope (site or org) controls which *sites* the token can access. Permissions control what actions the token can perform. Note that scope only restricts site-level operations — a site-scoped or org-scoped token with orgs:read can still list all your organizations.

Fine-Grained Permissions

Tokens use fine-grained permissions in resource:action format. By default, tokens get sites:read and deployments:write. Use --permissions to customize.

Permission	Description
`orgs:read`	List and view organizations
`sites:read`	List and view sites
`sites:write`	Create, update, delete sites (includes read)
`deployments:read`	View deployments, files, logs
`deployments:write`	Create deployments, upload, rollback (includes read)
`domains:read`	List and view custom domains
`domains:write`	Add, verify, delete custom domains (includes read)
`forms:read`	List forms and view submissions
`forms:write`	Update and delete forms (includes read)
`analytics:read`	View traffic analytics, goals, and funnels
`analytics:write`	Create and delete goals and funnels (includes read)

Key rule: write always implies read. A token with sites:write can also read sites.

Benefits

Scoped access - Deploy tokens are limited to a site or organization
Fine-grained - Control exactly which resources a token can access
Revocable - Delete tokens without affecting your account
Auditable - Track when tokens were last used
Secure - All tokens use the zd_ prefix for easy identification

token create

Create a new API token. You must specify either --org or --site to set the token scope.

Org Token

zerodeploy token create <name> --org <org>

Site Token

zerodeploy token create <name> --site <site>

Option	Description
`--org <org>`	Org slug (creates org-scoped token)
`--site <slug>`	Site slug (creates site-scoped token)
`--permissions <perms>`	Comma-separated permissions (e.g., `sites:read,deployments:write`)
`--expires <days>`	Token expiration in days (default: never)
`--json`	Output as JSON for scripting

bash

# Create an org token for CI/CD (deploys to any site in org)
zerodeploy token create "GitHub Actions" --org my-org

# Create a site token
zerodeploy token create "GitHub Actions" --site my-website

# Create a token with specific permissions
zerodeploy token create "Read Only" --org my-org --permissions sites:read,deployments:read

# Create a token with custom permissions
zerodeploy token create "CI" --site my-site --permissions deployments:write,sites:read,domains:read

Important: Save the token immediately. It will not be shown again.

token list

List your API tokens.

zerodeploy token list

Option	Description
`--type <user\|site\|org>`	Filter by token type (user=PAT, site/org=deploy)
`--site <slug>`	Filter by site slug
`--org <slug>`	Filter by org slug
`--json`	Output as JSON for scripting

bash

# List all tokens
zerodeploy token list

# List only site deploy tokens
zerodeploy token list --type site

# List only org deploy tokens
zerodeploy token list --type org

# List only PATs
zerodeploy token list --type user

token delete

Delete an API token.

zerodeploy token delete <tokenId>

bash

zerodeploy token delete zd_abc12345

You can use the full token ID or the token prefix.

Using Tokens in CI/CD

GitHub Actions

For Single Sites (Site Deploy Token)

Create a site deploy token: zerodeploy token create "GitHub Actions" --site <slug>
Go to your repository Settings → Secrets and variables → Actions
Click "New repository secret"
Name: ZERODEPLOY_TOKEN
Value: Paste the token

For Monorepos (Org Deploy Token)

Create an org deploy token: zerodeploy token create "GitHub Actions" --org <org>
Go to your repository Settings → Secrets and variables → Actions
Click "New repository secret"
Name: ZERODEPLOY_TOKEN
Value: Paste the token

Org tokens can deploy to any site in the organization, making them ideal for monorepos.

Then use it in your workflow:

yaml

- name: Deploy
  env:
    ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}
  run: npx @zerodeploy/cli deploy --dir dist

Other CI Systems

Set the ZERODEPLOY_TOKEN environment variable in your CI system's secrets configuration. The CLI will automatically use it for authentication.

Security Best Practices

Use deploy tokens (not PATs) for CI/CD pipelines
Create separate tokens for each CI/CD service
Use descriptive names to identify where tokens are used
Rotate tokens periodically by creating new ones and deleting old ones
Delete tokens immediately when they're no longer needed
Never commit tokens to your repository

Previous Custom Domains Next Forms