Authentication

All /v1 endpoints require an API key. Keys belong to a single organization (workspace) and inherit their creator’s current role and project/source assignments, limited by the key’s scopes.

Creating an API key

1. Open the Smoketest dashboard
2. Go to API keys in your user menu
3. Click New API key, give it a name, and select the scopes you need
4. Copy the key — it is shown only once. If you lose it, revoke it and create a new one.

Key format

Keys are prefixed with smkt_ followed by a URL-safe base64 string:

smkt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

Smoketest stores only a SHA-256 hash of your key, never the raw value. The key itself uniquely identifies both your identity and workspace — no additional headers are needed.

Required headers

Every request to a /v1 endpoint needs one header:

curl https://api.smoketest.sh/v1/projects \
  -H "Authorization: Bearer smkt_a1b2c3d4e5f6..."

Scopes

Each key is granted one or more scopes. Requests using a key without the required scope return 403 Forbidden.

Scopes cannot grant access beyond the creator’s current role and assignments. Viewer credentials have only read. Role changes and project/source removals take effect on subsequent requests; a removed member’s credentials stop working. Owner/Admin can inspect and revoke organization credentials; other members manage their own. Team and issue-management routes require an app session and are not exposed through /v1. Full billing access requires the Owner.

A single key can hold multiple scopes. For CI pipelines, read + run is usually enough.

Error responses

Inaccessible resource IDs return 404 Not Found. Lists contain only permitted resources.

Setting up a client

export SMOKETEST_API_KEY="smkt_a1b2c3d4e5f6..."

curl https://api.smoketest.sh/v1/projects \
  -H "Authorization: Bearer $SMOKETEST_API_KEY"