Service Tokens

Service tokens provide machine-to-machine authentication for CI/CD pipelines, Kubernetes pods, and other infrastructure. Unlike personal API tokens, they are tied to an organization rather than an individual user.

When to Use Service Tokens

Use Case	Token Type
CI/CD pipelines (GitHub Actions, GitLab CI, etc.)	Service Token
Kubernetes secret injection	Service Token
Infrastructure automation	Service Token
CLI interactive use	Personal API Token
Local development	Personal API Token

For a hosted agent or a recurring routine, use a machine token instead, or OIDC on GitHub Actions. A machine token is read-only, can be limited to specific keys, stops when idle and rotates with an overlap. Service tokens keep working as they always have: none of that applies to them.

Key Differences from Personal Tokens

• Not tied to a user lifecycle — if a team member leaves, service tokens continue working
• Scoped permissions — limit access to a specific organization, project, or environment
• Read or read/write — control whether the token can modify secrets
• Audit trail — service token actions are logged separately with [Service Token] labels

Scoping

Service tokens support three scope levels:

Scope	Access
Organization	All projects and environments in the org
Project	All environments in a specific project
Environment	A single environment only

Always prefer the narrowest scope possible. A CI/CD pipeline that only needs production secrets should use an environment-scoped token.

Permissions

Permission	Can Read Secrets	Can Write Secrets
read	Yes	No
read_write	Yes	Yes

Creating a Service Token

Dashboard

1. Navigate to your organization
2. Click Service Tokens in the top bar
3. Click New Service Token
4. Fill in the name, scope, permission, and optional expiration
5. Copy the token immediately — it won't be shown again

CLI

terminal

envshed token create-service \
  -o my-org \
  -n "GitHub Actions CI" \
  -s project \
  --project-id <project-uuid> \
  -p read \
  --expires-in 90

API

terminal

curl -X POST https://app.envshed.com/api/v1/service-tokens/my-org \
  -H "Authorization: Bearer $ENVSHED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Token", "scope": "project", "projectId": "...", "permission": "read"}'

Using a Service Token

Service tokens authenticate the same way as personal tokens — via the Authorization: Bearer header:

terminal

curl https://app.envshed.com/api/v1/secrets/my-org/my-project/production \
  -H "Authorization: Bearer envshed_svc_..."

Or with the CLI, with the token in the ENVSHED_TOKEN environment variable (set it from your CI secret store, not on the command line):

terminal

envshed pull -o my-org -p my-project -e production

Managing Service Tokens

Listing

terminal

envshed token list-service -o my-org

Revoking

terminal

envshed token revoke-service -o my-org --id <token-uuid>

Revoking a token immediately blocks all access. Any CI/CD pipelines using the token will fail on their next run.

list-service does not show machine tokens or OIDC sessions, and revoke-service and update-service refuse machine tokens. Manage those on the Hosted agents screen.

Best Practices

1. Use short expiration periods — 30-90 day tokens reduce risk if leaked
2. Use the narrowest scope — environment-scoped tokens over org-scoped
3. Use read-only when possible — most CI/CD pipelines only need to read secrets
4. Rotate regularly — create a new token, update your CI/CD config, then revoke the old one
5. Name tokens descriptively — include the service, environment, and purpose (e.g., "GitHub Actions - staging deploy")