Getting started

Authentication

The API uses the OAuth 2.0 client credentials grant. Each of your systems gets its own API client (a client_id and client_secret) with only the scopes it needs. A client exchanges its credentials for a short-lived bearer token and sends that token on every call.

API clients#

A client belongs to your company and only ever sees your company's data.
Wathiqaty creates, rotates and revokes clients at the request of your company's administrator. Ask for one client per system (core policy system, claims system, finance) so one can be revoked without stopping the others.
Secrets are stored hashed and can't be shown again. If one is lost or leaked, ask for a rotation: the old secret keeps working for 24 hours while you deploy the new one.
Optional per-client IP allow-list, recommended in production. Calls from other addresses get 403 ip_not_allowed.
Mutual TLS is available on request if your security policy requires it.

Scopes#

Scope	Grants
`packages:read`	List and read packages, pricing rules, readiness.
`packages:write`	Replace pricing rules, activate and deactivate, set your product code.
`policies:read`	List and read policies (including the policyholder's personal data) and their documents.
`policies:write`	Set your policy number, cancel a policy.
`cancellations:read`	List and read cancellation requests.
`cancellations:write`	Approve, reject, record manual refunds.
`claims:read`	List and read claims, documents and messages.
`claims:write`	Work claims: review, request documents, approve, reject, settle, close, message.
`finance:read`	Payments, commission ledger, balance, settlements, bordereaux.
`finance:write`	Submit settlement payment proof.
`webhooks:manage`	Manage webhook endpoints and deliveries.

A call without the scope it needs gets 403 missing_permission. Every endpoint in the reference shows its scope.

Getting a token#

POST /auth/partner/token with HTTP Basic authentication (client_id:client_secret) and a form-encoded body. Every field and error is in the reference.

Field	Meaning
`accessToken`	The bearer token (a signed JWT). Treat it as opaque.
`expiresIn`	Seconds until it expires: 900 (15 minutes).
`scope`	The scopes the token carries.

Using the token#

HTTP

GET /api/v1/partner/policies HTTP/1.1
Host: sandbox-api.wathiqaty.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

Cache it

The token route allows 10 requests a minute per client. Keep one token in memory and renew it shortly before it expires, or once after a 401 unauthorized:

Node.js

// Node.js: one token shared by all calls, renewed 60 s before expiry
let cached = { token: "", expiresAt: 0 }

export async function accessToken() {
  if (Date.now() < cached.expiresAt - 60_000) return cached.token
  const res = await fetch("https://sandbox-api.wathiqaty.com/api/v1/auth/partner/token", {
    method: "POST",
    headers: {
      Authorization:
        "Basic " + Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64"),
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: "grant_type=client_credentials",
  })
  const { data, error } = await res.json()
  if (!res.ok) throw new Error(`token: ${res.status} ${error.code}`)
  cached = { token: data.accessToken, expiresAt: Date.now() + data.expiresIn * 1000 }
  return cached.token
}

Security notes#

HTTPS only, TLS 1.2 or later.
Never put credentials or tokens in URLs, logs or front-end code. The API is for server-to-server use; browsers are refused by CORS.
Every call is recorded in Wathiqaty's audit log against the API client, including reads of personal data.