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

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

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

API

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:

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

Or with the CLI:

envshed token set envshed_svc_...
envshed pull -o my-org -p my-project -e production

Managing Service Tokens

Listing

envshed token list-service -o my-org

Revoking

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.

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")