Authentication

API Keys

SimuTest uses API keys for server-to-server authentication. Keys are prefixed to indicate the environment they belong to, making it easy to distinguish between production and sandbox usage.

Pass your API key in the Authorization header as a Bearer token on every request:

curl https://api.simutest.dev/v1/tests \
  -H "Authorization: Bearer st_live_abc123def456..."

Key Scopes

API keys can be scoped to limit access to specific resources. When creating a key, select only the scopes required for your use case to follow the principle of least privilege.

CI/CD pipelines typically only need tests:write and reports:read.

OAuth 2.0

For user-facing applications, SimuTest supports OAuth 2.0 with the authorization code flow. PKCE (Proof Key for Code Exchange) is supported and recommended for all clients, including server-side applications.

// Step 1: Redirect user to authorization URL
const authUrl = `https://auth.simutest.dev/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=tests:read tests:write reports:read&
  code_challenge=${codeChallenge}&
  code_challenge_method=S256`;

// Step 2: Exchange code for access token
const response = await fetch('https://auth.simutest.dev/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: authorizationCode,
    redirect_uri: 'https://yourapp.com/callback',
    code_verifier: codeVerifier,
    client_id: 'YOUR_CLIENT_ID',
  }),
});

const { access_token, refresh_token, expires_in } = await response.json();

RBAC Roles

Team members are assigned roles that control what they can view and modify within an organization. Roles are additive — higher roles inherit all permissions of lower roles.

Rate Limits

API requests are rate limited per API key. Limits are measured in requests per minute. When you exceed the limit, the API returns a 429 Too Many Requests response with a Retry-After header.