Skip to main content

Service Tokens

Service tokens are project-scoped API credentials that aren't tied to a person. Use them when you need GetWebstack access from somewhere a human won't be there to log in:

  • CI pipelines that deploy on merge
  • AI agents running unattended
  • One-off scripts and cron jobs
  • External monitoring or audit tooling

They use the same four-permission model as teams, so the principle of least privilege carries over.

Token shape​

FieldMeaning
nameHuman-readable label (ci-deploy, agent-rotate-secrets).
projectRequired. Tokens are always scoped to one project.
organizationOptional org context — useful when the project is shared across orgs.
expires_in_daysDefault 365. Set to 0 for non-expiring (not recommended).
can_change_gws_configsOff by default.
can_change_secretsOff by default.
can_delete_projectOff by default.

can_read is always on for any valid token.

Mint a token (UI)​

  1. Open the project → Service Tokens tab.
  2. Click New token.
  3. Name it, choose an expiry, tick the permissions you actually need.
  4. Click Create.
  5. Copy the token immediately — the full value is shown once and never again. Only the prefix is stored after that.

Store the value in your CI secret manager (GitHub Actions, GitLab CI, Vault, …) right after creation.

Use a token​

Authenticate the CLI with gws login --token:

gws login --token "$GWS_TOKEN"
gws status

This writes the token to ~/.getwebstackrc. Override the location with GWS_AUTH_FILE (a path to the credentials file — useful in CI when you want to keep it inside the workspace and discard it at the end of the job):

# .github/workflows/deploy.yml
- run: |
    gws login --token "$GWS_TOKEN"
    gws up
  env:
    GWS_TOKEN: ${{ secrets.GWS_DEPLOY_TOKEN }}
    GWS_AUTH_FILE: ${{ runner.temp }}/gws-auth
Use caseRecommended permissions
Read-only audit / monitoringnone beyond can_read
CI: deploy a fixed gws.jsoncan_read + can_change_secrets (only if the deploy rotates secrets)
CI: full deploy pipeline that may edit configcan_change_gws_configs + can_change_secrets
AI agent: rotate credentials on a schedulecan_change_secrets only
Disaster recovery / cleanup scriptcan_delete_project only on the target project

Mint a separate token per pipeline. It costs nothing and lets you revoke just one if it leaks.

Listing & revocation​

In the Service Tokens tab you can see name, prefix (the first 12 characters), org, project, permissions, expiry, and last_used_at. Click Revoke to invalidate a token immediately — in-flight requests fail on their next call.

Tokens auto-expire at expires_at; expired tokens return 401 and need to be re-minted.

Token rotation​

GetWebstack doesn't rotate tokens for you — they're meant to be cheap and replaceable. The standard playbook:

  1. Mint a new token with the same permissions.
  2. Update the CI secret store with the new value.
  3. Re-run the pipeline against the new token to confirm.
  4. Revoke the old token from the UI.

Security notes​

  • Treat tokens like passwords: never commit them, never paste them in chat, never log them.
  • The CLI logs the prefix of the token in use (e.g. gws_xxxxxxxx…), never the full value.
  • Tokens inherit no team membership — their permissions are exactly what you ticked at creation. Editing teams later does not affect existing tokens.
  • A revoked token cannot be undone. Mint a new one if you need to restore access.

See also​