Service accounts

Updated

Service accounts let you authenticate with the Customer.io CLI and other programmatic tools without using your personal credentials. They provide long-lived tokens with fine-grained access controls—ideal for AI coding assistants, CI/CD pipelines, and automation scripts.

You can setup multiple service accounts and multiple tokens per account. You might have different service accounts for different projects or departments in your account; and different tokens within each account to represent the different tools or users.

Create a service account

  1. Go to Account Settings > API Credentials and click the Service Accounts tab.
  2. Click Create Service Account.
  3. Enter a name and optional description.
  4. (Optional) check Read-only to permanently restrict the service account to GET requests.
  5. Click Create.

After creating the service account, you’re prompted to create your first token.

Create a token

A service account can have multiple tokens. Use separate tokens for different integrations so you can rotate or revoke them independently.

  1. In the Service Accounts tab, expand the service account.
  2. Click Create Token.
  3. Enter a name for the token.
  4. Set Expiration: No expiration, 30, 60, 90 days, or 1 year.
  5. (Optional) check Read-only to permanently restrict the token to GET requests.
  6. Click Create.

Save the token value starting with sa_live_. You can’t retrieve it later. You should store it in a secure location or use it with cio auth login so you don’t lose it.

Revoke a token

Revoking a token immediately invalidates it and any active sessions. Other tokens on the same service account aren’t affected.

  1. Expand the service account in the Service Accounts tab.
  2. Find the token and click Revoke.

Delete a service account

Deleting a service account revokes all of its tokens. This can’t be undone.

Store tokens securely

Service account tokens are long-lived and can grant full write access to your account. Treat them like passwords, and pick a storage method that matches how you’ll use the token.

Use caseRecommendationWhy
Local interactive developmentRun cio auth login to store your token in ~/.cio/config.jsonBuilt in; scoped to your user account
Local scripts or non-interactive runsA project-scoped .env file (git ignored), loaded with a tool like direnv or dotenvScoped to one project; rotate independently per project
CI/CD pipelinesYour CI provider’s secrets store (for example, GitHub Actions secrets), exposed as CIO_TOKENEncrypted at rest, masked in logs, auditable
Shared machinesYour OS keychain (macOS Keychain, secret-tool on Linux)Encrypted, per-user, no plaintext on disk

A few things to avoid:

  • Don’t put sa_live_ tokens in shell config files like ~/.zshrc or ~/.bashrc. These files are often synced to dotfile repos or backed up to cloud storage, where the token can leak.
  • Don’t commit .env files. If you use one, add it to your .gitignore and ship a .env.example with placeholder values for teammates.
  • Use one token per integration. Separate tokens let you rotate or revoke access for one tool without disrupting the others.

Read-only access

You can restrict access at two levels:

  • Read-only tokens: Check Read-only when creating a token. This permanently restricts every session from that token to GET requests.
  • Read-only sessions: When exchanging a token directly (not through the CLI), add --read-only to the request.
Copied to clipboard!
  Contents