Authentication

One credential, sent as a bearer token. Cookies are never read.

Request

GET /v1/suppliers HTTP/1.1
Host: api.aranis.ai
Authorization: Bearer ara_live_...

Creating a key

Keys are created in the Aranis app under Settings → Integrations. The secret is displayed once, at creation, and is never retrievable afterwards — store it in your secret manager before leaving the page.

Each key belongs to exactly one workspace. That is why no endpoint accepts an organization identifier as input: the tenant is derived from the credential, so a compromised key cannot be pointed at someone else's data.

Keys are bearer credentials — whoever holds one has the access it was granted. Keep them server-side, grant the narrowest scope set that does the job, and revoke immediately on any suspicion. Revocation takes effect on the next request.

Scopes

A key carries an explicit scope set, chosen at creation. Calling an endpoint without its scope returns 403 insufficient_scope naming the one you are missing — not a 401, because the credential itself is valid.

Scope	Grants
`suppliers:read`	List and read suppliers.
`suppliers:write`	Create suppliers.
`assessments:read`	List and read assessments, including their gaps.
`assessments:write`	Create assessments.
`reports:read`	Read report metadata and download report PDFs.
`assets:read`	List assets.
`assets:write`	Bulk upsert assets.
`risks:read`	Risk register, scores, matrices and acceptance letters.
`action-plans:read`	Read action plans and their items.
`action-plans:write`	Update an action plan item's status.
`alerts:read`	Read alerts and insights.
`context:read`	Business processes, products, processing activities, BIA, threats.
`evidence:read`	Include evidence metadata in assessment gaps.
`audit:read`	Read audit logs, for SIEM ingestion.
`webhooks:read`	Read webhook endpoints and delivery history.

`pii:read` is additive

pii:read grants nothing on its own. A key holding only that scope reaches no endpoint at all. What it does is un-redact personal fields on resources some other scope already allows.

Without it, those fields are absent from the payload — not null. The distinction matters more than it looks:

suppliers:read alone

{
  "id": "3f1a8c2e-...",
  "name": "Acme Cloud Inc",
  "domain": "acme.com",
  "criticality": "high"
}

suppliers:read + pii:read

{
  "id": "3f1a8c2e-...",
  "name": "Acme Cloud Inc",
  "domain": "acme.com",
  "criticality": "high",
  "email": "security@acme.com",
  "contacts": [{ "name": "Ana Souza", "email": "ana@acme.com" }]
}

An absent email means "this key may not see it". A null email would mean "this supplier has none". If the two were conflated, redacted data would look like missing data, and your reconciliation would quietly start deleting records that exist.

Practically: check 'email' in supplier, not supplier.email !== null.

Plan entitlement

The API is part of the Enterprise plan, and entitlement is re-checked on every request rather than only at key creation — a workspace that downgrades loses API access immediately rather than keeping it until its keys expire.

403

{
  "error": {
    "code": "plan_upgrade_required",
    "message": "The Aranis API is available on the Enterprise plan. Contact sales to enable it.",
    "request_id": "req_01J8Z9K2M4N6P8Q0R2S4T6V8"
  }
}

Rotation

Keys can be given an expiry at creation. To rotate without downtime: create the new key, deploy it, confirm traffic has moved by watching consumption in Settings → Integrations, then revoke the old one.