Authentication

All API requests are authenticated with a key you create in the SmoothDeploy console. Keys are org-scoped — one key can access any resource in your organization that its scopes allow.

To create a key, go to Organization → API Keys in the console. See API Keys for step-by-step instructions.

Request headers

Example

curl https://api.smoothdeploy.com/v1/tests \
  -H "x-api-key: sd_xxx..." \
  -H "x-project-id: 3f8a1b2c-1111-2222-3333-444455556666"

x-project-id is required whenever you call a tests, steps, or test-runs endpoint. Omitting it on those routes returns 400 { "message": "No active project" }. Supplying an ID that does not belong to your organization returns 404 { "message": "Project not found" }.

x-branch-id targets a specific branch within the project. When omitted, the request runs against the project's default branch. Supplying an ID that does not belong to the specified project returns 404 { "message": "Branch not found" }.

Key format

Keys start with sd_ followed by 48 hex characters:

sd_xxx...  (total length: 51 characters)

When you create a key, the full value is shown exactly once. Copy it to a secure secrets store immediately — it cannot be retrieved again after you close the dialog. The console only shows the first 8 characters (sd_XXXXX) as an identifier after creation.

Revoked and deleted keys

A revoked or deleted key returns 401 Invalid API key on every request. The response body is:

{ "message": "Invalid API key" }

If a key returns 401 unexpectedly, check the Organization → API Keys page to confirm the key has not been deleted.

Scope errors

A valid key that lacks the scope required for a route returns 403 { "message": "" }. Check which scopes the route requires in Scopes and recreate the key with the correct scopes.

Rate limits

Each API key is limited to 300 requests per minute. A request over the limit returns 429 with a Retry-After header that gives the number of seconds to wait:

{ "error": "Too many requests" }

When you poll a run for its status, keep the polling interval well inside this limit.

Security guidance

• Store keys in your CI/CD secret store (e.g. GitHub Actions Secrets, environment variables), never in source code.
• Grant only the scopes an integration actually needs. A key that only reads test results should have testRuns:read only — not tests:delete or tests:run.
• Rotate compromised keys immediately: delete the old key on the Organization → API Keys page and create a new one. Deletion takes effect instantly.
• API keys are org-scoped. A key created in one organization cannot access another.