Authentication

Cendis uses Personal Access Tokens (PATs) for CLI and API authentication. This page walks through generating, configuring, scoping, and rotating tokens.

Generate a Personal Access Token

1. Log in to your Cendis dashboard at app.cendis.ai
2. Open Settings → Personal Access Tokens
3. Click New Token
4. Give it a descriptive name (laptop-2026-04, github-actions-prod)
5. Set an expiration date (recommended: 90 days for human use, 365 days for CI)
6. Choose scopes — see Scopes below
7. Click Create — copy the token immediately, you will not see it again

Security note: Tokens are shown exactly once. If you lose a token, revoke it and create a new one rather than trying to recover it.

Configure the CLI

The CLI looks for the token in this order:

1. --token <value> flag passed to the command
2. CENDIS_TOKEN environment variable
3. Error if neither is set

Local development

Add the token to your shell profile so it persists across sessions:

# ~/.zshrc or ~/.bashrc
export CENDIS_TOKEN="cendis_pat_..."

Reload your shell:

source ~/.zshrc

Verify it’s loaded:

cendis whoami

You should see your username and org. If you get 401 Unauthorized, the token is missing, expired, or revoked.

Per-project tokens

If you work across multiple orgs, you can scope a token to a single project using a .envrc (with direnv) or a .env file (with dotenvx):

# .envrc — direnv loads this when you cd into the project
export CENDIS_TOKEN="cendis_pat_..."

Make sure .envrc and .env are in your .gitignore — never commit tokens.

Configure CI/CD

For automated environments, store the token as a secret in your CI provider, then expose it as CENDIS_TOKEN.

GitHub Actions

# .github/workflows/governance-check.yml
name: Cendis governance check

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - name: Install Cendis CLI
        run: bun install -g @cendis/cli
      - name: Check for asset drift
        env:
          CENDIS_TOKEN: ${{ secrets.CENDIS_TOKEN }}
        run: cendis status --strict

--strict exits non-zero on any drift — perfect for CI gates.

GitLab CI

governance:
  stage: test
  image: oven/bun:1
  variables:
    CENDIS_TOKEN: $CENDIS_TOKEN # set in project CI/CD variables
  script:
    - bun install -g @cendis/cli
    - cendis status --strict

CircleCI, Buildkite, Jenkins, etc.

Same pattern — store the token as a secret, expose it as CENDIS_TOKEN in the job environment.

Scopes

When creating a PAT, you choose which scopes it grants. Use the smallest set that gets the job done.

Scope	Allows	Use for
read:assets	List assets, pull files	Most CLI usage, CI checks
write:assets	Publish new asset versions	Asset authors, publish pipelines
approve:assets	Approve / reject pending versions	Workspace admins
read:audit	Read audit log entries	Compliance integrations
admin:org	Manage members, workspaces, billing	Org admins only

A typical engineer needs read:assets. A CI pipeline needs read:assets (and write:assets if it publishes). Don’t grant admin:org to anything that isn’t human.

Rotate tokens

PATs should be rotated on a schedule. Recommended cadence:

• Human PATs: every 90 days
• CI PATs: every 180-365 days
• Immediately: if a laptop is lost, an employee leaves, or a token is exposed in logs

To rotate:

1. Create the new token in the dashboard
2. Update CENDIS_TOKEN in shell profile / CI secrets
3. Verify it works (cendis whoami in shell, run a CI build)
4. Revoke the old token from the dashboard

Cendis emails the token owner before expiration so rotations don’t surprise you.

Revoke a token

1. Dashboard → Settings → Personal Access Tokens
2. Find the token by name or last-used timestamp
3. Click Revoke

Revocation is immediate — any in-flight requests with that token will start returning 401.

Troubleshooting

401 Unauthorized

• Token is wrong, expired, or revoked
• Run cendis whoami to confirm
• Regenerate from the dashboard

403 Forbidden — missing scope

• Token is valid but doesn’t have the required scope for the action
• Check the scopes column on the token in the dashboard
• Create a new token with the right scopes (you can’t add scopes to an existing token)

Token works locally but not in CI

• Most common cause: secret name mismatch — check that the CI secret is exposed as CENDIS_TOKEN exactly
• Second most common: token was accidentally truncated when copied — regenerate

Lost the token

• Tokens cannot be recovered — they’re shown once at creation
• Revoke and recreate

Next steps

• CLI Quickstart — install and use the CLI
• Concepts — understand the governance model
• FAQ — common questions