Authenticate

Every rule-line integration call is a Bearer token on the Authorization header, checked before anything else in the request runs. There is no API-key management endpoint in this contract — a tenant administrator issues scoped API keys from the rule-line dashboard, one per integration, so a leaked key can be revoked without touching any other integration.

Scopes

Each API key carries one or more of four scopes:

Scope	Grants
submit	Uploading/retiring documents and submitting jobs (POST /documents, DELETE /documents/{documentId}, POST /jobs).
read	Polling job status, reading results, and listing run history (GET /jobs/{id}, GET /jobs/{id}/result, GET /runs, GET /runs/{runId}/delivery), and browsing reference data (GET /datasets and the dataset detail, version and row routes).
webhook_destination_override	Naming a non-default webhook destination on POST /jobs via webhookDestinationId. Never grants an arbitrary outbound URL — only selection among the tenant's own already-registered destinations.
dataset_write	Pushing reference data (POST /datasets/{datasetId}/versions). It only lets a key push rows to a dataset a ruleset already declares — see Push reference data. Reading reference data needs only read.

A key can carry any combination. Request only the scopes an integration actually needs — submit and read together cover the common case of submitting jobs and polling for their outcome.

Verifying your credentials

The lightest authenticated round trip is listing your tenant's rulesets, which only needs the read scope:

import { client, listRulesets } from '@one-unity/rule-line-sdk';

client.setConfig({
  baseUrl: 'https://api.rule-line.example.com',
  auth: 'rl_key_your_api_key',
});

const result = await listRulesets({ query: { limit: 1 } });
if (result.error) {
  throw new Error(`authentication failed: ${result.error.code}`);
}
console.log(`authenticated — ${result.data.items.length} ruleset(s) visible`);

Constructing the client with auth sets the raw token; the generated client adds the Bearer prefix itself — never pass an already-prefixed value.

Equivalent raw HTTP

GET /rulesets?limit=1 HTTP/1.1
Host: api.rule-line.example.com
Authorization: Bearer rl_key_your_api_key

Expected response

{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "expense-report-matching",
      "status": "active",
      "version": 3,
      "activatedAt": "2026-08-01T00:00:00.000Z",
      "createdAt": "2026-07-20T00:00:00.000Z"
    }
  ],
  "nextCursor": null
}

An empty items array with a 200 status is still a successful authentication — it means the key is valid but no ruleset matches yet.

Errors

A missing, malformed, or revoked key renders AUTHENTICATION_REQUIRED. A key that is valid but lacks the scope a route requires renders FORBIDDEN — the two are deliberately distinguishable, so an integration can tell "log in again" apart from "ask your administrator for another scope." See the full GET /rulesets reference for the complete request/response schema.