Authentication

How to authenticate with TrigRun — email verification, roles, API tokens, and workspace switching.

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

New accounts require email verification before you can create jobs, secrets, or other resources. You can browse the dashboard immediately, but write actions are blocked until you verify.

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",
    "timezone": "UTC"
  }'

Returns 202 Accepted:

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

Check your inbox for a verification link. 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 all features are unlocked. After 48 hours of normal usage, you are promoted to trusted.

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:

Role	What they can do
Owner	Everything. Billing, team management, API tokens, workspace settings, plus all admin actions.
Admin	Jobs, secrets, notification channels, execution replay. All operational actions.
Member	Read-only access. View jobs, executions, and settings but cannot create or modify resources.

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 (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

Operation	Owner	Admin	Member	API Token
View jobs, executions, secrets	Yes	Yes	Yes	Yes
Create/update/delete jobs	Yes	Yes	No	Yes (inherits creator role)
Create/delete secrets	Yes	Yes	No	Yes (inherits creator role)
Manage notification channels	Yes	Yes	No	Yes (inherits creator role)
Create/revoke API tokens	Yes	No	No	No
Manage team members	Yes	No	No	No
Update billing/plan	Yes	No	No	No
Update workspace settings	Yes	No	No	No
Transfer ownership	Yes	No	No	No

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 cronctl CLI stores credentials in ~/.cronctl/config.json:

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

You can also set credentials via environment variables:

export CRON_API_URL="https://api.trigrun.com"
export CRON_TOKEN="cron_pat_abc123def456..."

Environment variables take precedence over the config file.

Error responses

Code	Error	When
401	`unauthorized`	Missing or invalid token
401	`invalid_credentials`	Wrong email or password
401	`token_orphaned`	API token's creator was deleted
401	`token_creator_removed`	API token's creator left the workspace
403	`email_not_verified`	Write action before email verification
403	`insufficient_role`	Action requires a higher role
403	`workspace_restricted`	Workspace is restricted
403	`account_restricted`	User account is restricted
429	`rate_limited`	Too many requests (includes `Retry-After` header)

Authentication

On this page