Authentication

TrigRun supports two authentication methods. Both use the Authorization: Bearer <token> header.

Signup and email verification

New accounts may require email verification before you can create jobs, secrets, or other resources. When verification is enabled, signup returns 202 Accepted and the response includes email_verification_required: true.

Sign up:

curl -X POST https://api.trigrun.com/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "email": "[email protected]",
    "password": "your-secure-password",
    "workspace_name": "My Workspace"
  }'

Returns 201 Created when verification is auto-enabled, or 202 Accepted when verification is required:

{
  "token": "eyJhbGciOi...",
  "workspace": { "id": "clx...", "name": "My Workspace" },
  "user": {
    "id": "clx...",
    "name": "Alice",
    "email": "[email protected]",
    "trust_level": "pending_verification"
  },
  "email_verification_required": true
}

When verification is required, check your inbox for a verification link and click it to activate your account. You can also resend the verification email:

curl -X POST https://api.trigrun.com/v1/auth/resend-verification \
  -H "Authorization: Bearer $TOKEN"

Once verified, your trust_level changes to verified and write actions are unlocked.

JWT tokens (user sessions)

JWT tokens are issued on signup and login. They identify the user, workspace, and role, and expire after 7 days.

Log in:

curl -X POST https://api.trigrun.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password"
  }'

{
  "token": "eyJhbGciOi...",
  "workspace": { "id": "clx...", "name": "My Workspace" },
  "user": { "id": "clx...", "name": "Alice", "trust_level": "trusted" },
  "workspaces": [
    { "workspace": { "id": "clx...", "name": "My Workspace" }, "role": "owner" },
    { "workspace": { "id": "cly...", "name": "Acme Corp" }, "role": "admin" }
  ]
}

Use the token in subsequent requests:

curl https://api.trigrun.com/v1/me \
  -H "Authorization: Bearer eyJhbGciOi..."

Workspace switching

If you belong to multiple workspaces, your token is scoped to the first workspace by default. Switch to a different workspace:

curl -X POST https://api.trigrun.com/v1/auth/switch-workspace \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "workspace_id": "cly..." }'

This returns a new JWT scoped to the target workspace.

List your workspaces:

curl https://api.trigrun.com/v1/workspaces \
  -H "Authorization: Bearer $TOKEN"

Roles

Every workspace member has one of three roles:

The workspace creator is automatically the owner. Ownership can be transferred via POST /v1/workspace/transfer.

API tokens (machine credentials)

API tokens are long-lived credentials scoped to a workspace. Use them for CI/CD pipelines, scripts, and integrations. Only workspace owners can create and manage tokens.

API tokens start with cron_pat_ and don't expire (until revoked). They inherit the role of the user who created them — if the creator is later removed from the workspace or restricted, the token stops working.

Create a token in the app

If you're using the TrigRun app, the easiest way to create a token is:

1. Sign in at trigrun.com.
2. Open API Keys in the app navigation.
3. Enter a descriptive token name such as ci-pipeline or production-worker.
4. Click Create Token.
5. Copy the raw token immediately and store it in your password manager, secret manager, or CI environment.

Copy it before leaving the page

TrigRun only shows the full token value once, right after creation. After that, the UI only shows the masked value, so if you close the screen before copying it, you'll need to revoke it and create a new one.

Create a token (owner only):

curl -X POST https://api.trigrun.com/v1/api-tokens \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-pipeline" }'

{
  "id": "clx...",
  "name": "ci-pipeline",
  "masked_value": "cron_pat_abc1••••",
  "token": "cron_pat_abc123def456..."
}

The raw token value is returned only once at creation time. Store it securely.

Revoke a token (owner only):

curl -X DELETE https://api.trigrun.com/v1/api-tokens/TOKEN_ID \
  -H "Authorization: Bearer $JWT_TOKEN"

Permission matrix

API tokens inherit the permissions of the user who created them, so they can perform the same actions that user could perform at the time the token was created.

Workspace restriction

If a workspace is restricted (e.g., for a billing or TOS issue), all write operations are blocked but read access remains available. The restriction reason is included in the workspace object:

{
  "id": "clx...",
  "name": "My Workspace",
  "restricted": true,
  "restriction_reason": "Payment failed"
}

CLI authentication

The trigrun CLI stores credentials in ~/.trigrun/config.json:

trigrun login -e [email protected] -p your-secure-password
trigrun whoami

If you want token-based CLI auth for CI, bots, or non-interactive scripts, create a workspace API token in API Keys and then either save it to the CLI config:

trigrun token cron_pat_abc123def456...
trigrun whoami

You can also set credentials via environment variables:

export TRIGRUN_API_URL="https://api.trigrun.com"
export TRIGRUN_TOKEN="cron_pat_abc123def456..."

Environment variables take precedence over the config file.

Error responses