Authenticating with the REST API

The REST API uses bearer-token auth. You generate a Client ID + Client Secret in the dashboard; subsequent requests include the Secret as a bearer token in the Authorization header. Available on Management+ plans.

Base URL

text
https://api.semoptimiser.com/v1

Generate credentials

1. Settings → API Credentials.
2. Click Generate credentials.
3. Copy the Client Secret immediately – it's shown in full once and masked after.
4. Store in your secrets manager (1Password, AWS Secrets Manager, env var).

Authenticate a request

bash
curl https://api.semoptimiser.com/v1/audits \
  -H "Authorization: Bearer sk_live_yourSecretHere" \
  -H "Content-Type: application/json"

The Client ID is implicit (we derive your workspace from the Secret). All requests require the Authorization header.

Token format

Two prefixes: `sk_live_` for production, `sk_test_` for test mode. Both are 48-character tokens with random suffixes. They are not JWTs – they're opaque to clients.

Rate limits

Every response includes rate-limit headers:

http
RateLimit-Limit: 600
RateLimit-Remaining: 547
RateLimit-Reset: 47

When you exceed the limit you get a 429 with a Retry-After header in seconds. Back off and retry.

Error response shape

json
{
  "error": {
    "code": "validation_error",
    "message": "url is required",
    "param": "url"
  }
}

HTTP status codes: 200 success, 400 client error, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict, 422 validation failed, 429 rate-limited, 5xx server error.

Rotate the Secret

Settings → API Credentials → Regenerate. Old Secret is invalidated within 1 minute. Update every script and environment using the old Secret – no grace period.

Revoke entirely

Settings → API Credentials → Revoke. Both Client ID and Secret are invalidated. Any script using them returns 401.

SDKs

Official SDKs: JavaScript / Node (`npm install @semoptimiser/sdk`), Python (`pip install semoptimiser`), Go (`go get github.com/semoptimiser/go-sdk`). Each handles auth, retries and rate-limit backoff for you.