Sanctions screening API authentication and key scopes

Send the key in the Authorization header as Bearer followed by the secret. A key starting sk_test_ belongs to the sandbox. A key starting sk_live_ belongs to production. You cannot change the key's environment with a request parameter.

Scopes are the actions the key can perform. Use sources:read to discover sources, screenings:write to screen, and results:read to fetch evidence. Batches, monitors, cases, usage, and webhooks have their own scopes. Grant only the actions this integration needs.

Every example uses https://www.sanctionskit.com/api/v1 as its base URL. Send application/json on JSON writes and Authorization: Bearer on authenticated calls. A key is permanently associated with one organization and either sandbox or production; X-SK-Environment does not switch a key into another environment. Create separate keys for each environment.

In the API reference, Headers, path and query parameters describes values sent outside the body. Request body describes the JSON object. Required properties are marked independently from required headers. Optional means a property can be omitted; nullable means it can be present with null. Follow the documented field spelling: some resource responses use snake_case and others use camelCase.

• Single screening: screenings:write; retrieve results and evidence: results:read.
• Batches and private upload: batches:write; read batch progress and files: results:read.
• Create, edit, pause, resume or delete monitors: monitors:write; read health and events: results:read.
• Discover sources and published policies: sources:read. Read usage: usage:read.
• Register, list, disable and retry webhook endpoints or deliveries: webhooks:write.
• Human review, counterparty edits, policy publication, organization settings and team/key administration require the documented signed-in human permissions. Giving a key an additional scope does not turn it into a human session.

Save this file as sk-api.mjs and set SANCTIONSKIT_API_KEY in your server environment. The examples on the screening, batch, monitoring and evidence pages can import it. It works with the ordinary JSON data envelope, including array and page responses; downloadable evidence, CSV, PDF, NDJSON and the upload token exchange have separate formats.

The helper does not retry automatically. HTTP errors throw with status, code, requestId, optional details and Retry-After. A timeout or invalid response also throws. Catch these at your job or request boundary and record only the status, code and request ID; use the error guide to decide whether the same operation can be retried.

// Save as sk-api.mjs. Requires Node.js 20 or later.
export async function api(path, { method = 'GET', body, key } = {}) {
  const token = process.env.SANCTIONSKIT_API_KEY;
  if (!token) throw new Error('Set SANCTIONSKIT_API_KEY on your server.');
  const response = await fetch('https://www.sanctionskit.com/api/v1' + path, {
    method,
    headers: {
      Authorization: 'Bearer ' + token,
      ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
      ...(key ? { 'Idempotency-Key': key } : {}),
    },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
    signal: AbortSignal.timeout(15000),
  });
  const payload = await response.json().catch(() => null);
  const requestId = payload?.error?.requestId ?? response.headers.get('X-Request-Id');
  if (!response.ok) {
    // Keep diagnostics available to your form, without logging subjects or secrets.
    const error = new Error('SanctionsKit request failed.');
    Object.assign(error, {
      status: response.status,
      code: payload?.error?.code ?? 'invalid_response',
      requestId,
      details: payload?.error?.details,
      retryAfter: response.headers.get('Retry-After'),
    });
    throw error;
  }
  if (!payload || !Object.hasOwn(payload, 'data')) {
    throw new Error('Unexpected response envelope.');
  }
  return payload.data;
}

An authorized person creates a key in the dashboard. Copy the secret when it appears; it is shown once. SanctionsKit retains secure verification material. You can set a future expiresAt when creating a key. An expired key fails authentication and stops using an active-key slot. Without expiresAt, the key has no automatic expiry.

For a gradual replacement, create a second key, update your integration, verify it works, and revoke the old key. The Rotate action replaces and revokes the old key in one step while keeping its environment, scopes, and expiry.

Revocation clears the handling instance after commit. Another warm instance may accept the key until its authorization cache expires: 30 seconds by default, at most 60 seconds. Key expiry is checked on every request. Revoked or malformed credentials do not fall back to a browser session or demo identity.

Keep keys out of browser code, URLs, source control, analytics, and logs. People sign in through secure sessions with server-side membership checks. Key management and team administration require human permissions. A key cannot act as the account owner.

Treat 401 as an authentication problem and 403 as an authorization problem. Stop retries that cannot succeed without changing credentials or permissions. Record the request ID and error code for support, without logging the secret or submitted subject. Use the account sign-in flow for recovery, verification, and multi-factor authentication.

Frequently asked questions