Personal access tokens

A personal access token (PAT) is a credential you create to authenticate to the Loha API and the CLI without a browser session.

A token:

• acts as you: actions taken with it are attributed to your user and audited;
• is bound to a single workspace: it can only ever touch that workspace's data, no matter what scopes it carries;
• can only do what its scopes allow: there is no all-access token;
• stops working the moment you revoke it, it expires, or you lose access to its workspace.

For CI/CD, use a service account instead

A PAT acts as you, so a pipeline using it breaks the day you're offboarded. For unattended automation, create a workspace-owned service account and use its key. Same bearer credential, but it survives staff changes and is managed by workspace admins. See Using the CLI in CI/CD.

Create a token

Any workspace member, admin or owner can create a token. Guests cannot. The token is created in the workspace whose settings you are on.

Member self-service

Not enabled everywhere yet

Creating tokens as a member is rolling out workspace by workspace. If you are a member and don't see the API Keys tab, ask a workspace admin.

1. In the dashboard, open the workspace the token should act in and go to Settings → API Keys. The dashboard calls personal access tokens API keys; they are the same credential.
2. Click Create API key.
3. Fill in:
   • Name: a label so you can recognize the token later (e.g. CI deploy token).
   • Scopes: the permissions the token grants (see below). Pick the minimum the job needs.
   • Expires in (days): members must set an expiry (1–365 days; the dialog suggests 90, and if you create a token through the API without expiresInDays, Loha sets 90 days). Admins and owners may leave it blank for a token that never expires, but an unattended job should use a service account instead.
4. Click Create API key. The token value (loha_…) is shown once. Copy it immediately and store it somewhere safe. Loha only stores a hash, so it cannot show the value again.

Scopes

Grant only the scopes a token needs:

Scope	Grants
builds:read	Read builds and logs
builds:write	Mutate builds (e.g. cancel a running build)
triggers:run	Fire a pipeline run (manual / deploy)
triggers:write	Create / update triggers
pipelines:read	Read triggers, validate and plan .loha.yml
pipelines:write	Create / update / delete saved pipelines
repos:read	List and read repositories
repos:code:read	Read source code (diffs and file contents) in the Changes view
repos:write	Import / connect repositories
connections:read	List repo hosts (never the stored token)
connections:write	Create / update repo hosts
variables:read	Read variable metadata (never values)
variables:values:read	Read plain variable values in a build plan (never secrets)
variables:write	Create / update / delete variables
registry:read	Read registry credential config (never the password)
registry:write	Create / update / delete registry credentials
targets:read	Read deploy target config (never the SSH credential)
targets:write	Create / update / delete deploy targets, test a connection
webhooks:read	Read outbound webhook config and delivery history (never the secret)
webhooks:write	Create / update / delete / rotate outbound webhooks
members:read	List workspace members and pending invitations, incl. 2FA status
members:write	Manage workspace members and invitations
service_accounts:write	Create / update / delete service accounts
workspace:write	Update workspace profile / settings
audit:read	Read audit logs

repos:code:read and variables:values:read are opt-in: they need at least the member role, and the "Read only" preset does not include them. variables:values:read lets a loha plan show plain variable values instead of names only; secret values are never returned by any scope. Tokens created before a scope existed do not gain it.

For example, a CI job that only kicks off a deploy needs just triggers:run; one that also reports build status needs builds:read too.

Listing members now requires members:read

Reading the member list and pending invitations used to need no scope at all — any token bound to the workspace could do it. Because that list reports each member's two-factor status, it now requires members:read.

Tokens created before this change do not have the scope, so calls to GET /api/customer/workspaces/{slug}/members and .../invitations return 403 API key does not have required scope. Create a replacement token with members:read selected and swap it in. Nothing else about the token changes, and no other endpoint is affected.

What your role allows

A token can only hold scopes your workspace role allows. The create dialog offers only those, and Loha refuses anything else with 403 scope_exceeds_role. If your role is lowered later, your existing tokens shrink with it: calls that need a scope your new role lacks get 403. If you are removed from the workspace, your tokens are revoked.

You can hold at most 10 active tokens per workspace. Revoke one to create another.

Creating a token asks you to confirm your password. If you signed up with a single sign-on provider and have no password yet, set one first in Account → Security.

Use a token

Send the token as a bearer token (or the x-api-key header) on API requests:

TOKEN="loha_xxxxxxxxxxxxxxxxxxxx"

# Verify the token and see which workspace + scopes it has
curl https://app.loha.longtumlab.com/api/v1/whoami \
  -H "Authorization: Bearer $TOKEN"

# Trigger a deploy
curl -X POST https://app.loha.longtumlab.com/api/v1/triggers/$TRIGGER_ID/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main"}'

With the CLI, run loha login --token loha_…. It's saved to a config file (~/.config/loha/config.yaml, mode 0600) and used automatically for subsequent commands.

In CI, store the token as a masked/secret variable (e.g. a GitLab CI variable or GitHub Actions secret) and pass it via the Authorization header. Never hard-code it.

Revoke a token

On Settings → API Keys, click Revoke next to a token. Revocation is immediate: the next request using that token gets 401. Revoke a token as soon as you suspect it has leaked.

Members (and guests) see and revoke only their own tokens. Admins and owners see every token in the workspace, with its owner, and can revoke any of them.

To rotate a token, create a new one with the same scopes, switch your tooling to it, then revoke the old one.

Security best practices

• Treat a token like a password. Anyone with it can act as you in its workspace.
• Scope minimally and set an expiry for automation tokens.
• Never commit tokens to a repository or paste them into logs. Loha redacts obvious secret patterns from build logs, but don't rely on that.
• Prefer per-purpose tokens (one per CI job / machine) so you can revoke one without disrupting the others.
• A token can never reach outside the workspace it was issued for: the workspace is bound to the token, not to your dashboard session.

See also

• Service accounts: workspace-owned machine identities for CI/CD.
• Using the CLI in CI/CD: authenticate a pipeline with a service account key.
• API reference: endpoints, rate limits, error format.
• CLI: loha login and the command-to-endpoint map.