API Tokens

Creating and using personal access tokens for the SculptOps REST API.

Overview

API tokens let you authenticate against the SculptOps REST API without using your session cookie. They are useful for CI/CD integrations, scripts, and external tooling.

Tokens are scoped to your user account and inherit your role within each organization. A token created by a member cannot perform admin-only actions.

Creating a token

Go to Settings → API Tokens → New token. Give it a descriptive name (e.g. github-actions-deploy) and an optional expiry date. After saving, the token value is shown once — copy it immediately.

Danger

Token values cannot be retrieved after the creation dialog is closed. If you lose a token, delete it and create a new one.

Using a token

Pass the token as a Bearer token in the Authorization header:

bash

curl https://your-instance.example.com/api/playbooks \
  -H "Authorization: Bearer ag_live_abc123xyz..."

Common API operations

List playbooks

bash

GET /api/playbooks
Authorization: Bearer <token>

# Response
{
  "playbooks": [
    { "id": "abc123", "name": "Deploy app", "updatedAt": "2025-01-15T10:30:00Z" },
    ...
  ]
}

Trigger a playbook run

bash

POST /api/executions
Authorization: Bearer <token>
Content-Type: application/json

{
  "playbookId": "abc123",
  "inventoryId": "def456",
  "extraVars": { "env": "production" },
  "tags": ["deploy"]
}

Get execution status

bash

GET /api/executions/:id
Authorization: Bearer <token>

# Response
{
  "id": "exec789",
  "status": "success",  // running | success | failed | cancelled
  "startedAt": "2025-01-15T10:31:00Z",
  "finishedAt": "2025-01-15T10:33:42Z",
  "exitCode": 0
}

Stream execution logs (SSE)

bash

GET /api/executions/:id/logs/stream
Authorization: Bearer <token>
Accept: text/event-stream

# Each event:
data: {"line": "TASK [ping] *****", "level": "ok", "ts": 1736934660}

List inventory hosts

bash

GET /api/inventories/:id
Authorization: Bearer <token>

Token management

Operation	Endpoint
List tokens	GET /api/tokens
Create token	POST /api/tokens
Delete token	DELETE /api/tokens/:id
Revoke all tokens	DELETE /api/tokens

Token expiry

Tokens with an expiry date are automatically invalidated after the expiry timestamp. Expired tokens return 401 Unauthorized. You can see the expiry date of all your tokens in Settings → API Tokens.

Tip

Set short expiry times (7–30 days) for tokens used in automated pipelines and rotate them regularly.

Permissions & Roles

Audit Log