API Tokens

API tokens provide programmatic access to the SKE API. They are designed for CI/CD pipelines, scripts, and integrations that need to authenticate without interactive login.

Creating a token

Create tokens through the dashboard or API. Each token has:

• Name — a descriptive label (e.g., “GitHub Actions — production deploy”)
• Permissions — an explicit allowlist of actions the token can perform
• Scopes — resource boundaries the token operates within
• Expiration — optional expiry date

How token auth works

Set the SKE_API_TOKEN environment variable to authenticate:

export SKE_API_TOKEN=ske_tok_abc123...
ske deploy --env production

When SKE_API_TOKEN is set, the CLI uses it directly instead of the credential file. The token is sent as a Bearer token in the Authorization header.

Permission model

API tokens use a Cloudflare-style policy model:

1. Permission allowlist — the token explicitly lists which actions it can perform (e.g., deploy, secret:view)
2. Resource scopes — the token specifies which resources it can act on, scoped by organization, workspace, project, or environment
3. Creator ceiling — a token can never have more permissions than its creator. If the creator loses a permission, the token effectively loses it too.

Three-step auth check

Every API call with a token goes through:

1. Permission check — is the requested action in the token’s permission allowlist?
2. Scope check — is the target resource within the token’s allowed scopes?
3. Creator check — does the token’s creator still hold this permission on the resource?

All three must pass. This means tokens are automatically constrained if the creator’s access changes — no need to rotate tokens when adjusting team permissions.

Example: CI/CD deploy token

A token for a pipeline that deploys the shop project:

Name:        GitHub Actions — shop
Permissions: project:view, environment:view, deploy
Scopes:
  project:     shop
Expires:     2027-01-01

These are the permissions a CI token needs, and the ones the project setup’s “Create token” link fills in:

• deploy starts the deployment and lets the CLI follow it to the end
• project:view and environment:view let the CLI read the project and its environments: ske link, ske deploy list, and the app URL it prints after a deploy
• secret:view as well for a static site, whose build gets the environment’s variables
• environment:clearance as well to deploy to a protected environment

This token can only deploy to the environments of the shop project. It cannot manage secrets, modify infrastructure, or deploy other projects.

Using tokens in CI

The examples download the install script and then run it. Piped straight into sh (curl ... | sh), a failed download runs an empty script and the step passes, so the job only fails later with ske: command not found.

The runner builds the application image, so it needs Docker, and the build installs the app’s Composer dependencies. For private Composer packages, add a COMPOSER_AUTH secret and pass it to the deploy step’s environment, next to SKE_API_TOKEN (see Build Configuration).

GitHub Actions

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install SKE CLI
        run: |
          curl -fsSL https://get.ske.io/install.sh -o /tmp/ske-install.sh
          sh /tmp/ske-install.sh
      - name: Deploy
        run: ske deploy --env production
        env:
          SKE_API_TOKEN: ${{ secrets.SKE_API_TOKEN }}

GitLab CI

deploy:
  stage: deploy
  script:
    - curl -fsSL https://get.ske.io/install.sh -o /tmp/ske-install.sh
    - sh /tmp/ske-install.sh
    - ske deploy --env production
  variables:
    SKE_API_TOKEN: $SKE_API_TOKEN
  only:
    - main

Token management

• Prefix — tokens start with ske_tok_ for easy identification in logs and environment variable dumps
• Revocation — revoke tokens immediately through the dashboard. Revoked tokens are rejected on the next API call.
• Last used — the dashboard shows when each token was last used
• Rotation — create a new token, update your CI secrets, then revoke the old one

Best practices

• Create separate tokens per pipeline/environment — don’t share a single token across all CI jobs
• Use the narrowest possible permissions and scopes
• Set an expiration date and rotate regularly
• Store tokens in your CI provider’s secret management, never in code