Authentication.

Keys

• A key is made in the portal: project → API keys → New key. It belongs to that one project, so no endpoint takes a project id — the key already says which project, and nothing a call sends can reach another one.
• It begins af_, so a leaked one is easy to find in a log or a repository scan.
• It exists once, in the portal's answer when it is made. ArdaForm keeps only its SHA-256 and its first eight characters (the prefix you see in lists). Lose it and make another; nothing can show it again, and no answer ever repeats it.
• How many keys an account may have is its package's api_keys. The rate limit is per account, so a second key does not buy a second allowance.
• Keep it on a server. This API answers no cross-origin request, so a key in a web page does not work — and would be a key anybody can read.

Sending it

As a bearer token, on every call except GET /v1 and GET /v1/openapi.json:

Authorization: Bearer af_…

curl "https://api.ardaform.net/v1/auth"

const res = await fetch('https://api.ardaform.net/v1/auth')
const answer = await res.json()
if (!res.ok) throw new Error(`${res.status} ${answer.error.code}: ${answer.error.message}`)
console.log(answer)

import requests

r = requests.get(
    "https://api.ardaform.net/v1/auth",
)
answer = r.json()
if not r.ok:
    raise RuntimeError(f"{r.status_code} {answer['error']['code']}: {answer['error']['message']}")
print(answer)

{
  "error": {
    "code": "NO_KEY",
    "message": "Send your API key as `Authorization: Bearer af_…`."
  }
}

curl "https://api.ardaform.net/v1/auth" \
  -H "Authorization: Bearer af_this-key-does-not-exist"

const res = await fetch('https://api.ardaform.net/v1/auth', {
  headers: {
    Authorization: 'Bearer af_this-key-does-not-exist'
  }
})
const answer = await res.json()
if (!res.ok) throw new Error(`${res.status} ${answer.error.code}: ${answer.error.message}`)
console.log(answer)

import requests

r = requests.get(
    "https://api.ardaform.net/v1/auth",
    headers={"Authorization": "Bearer af_this-key-does-not-exist"},
)
answer = r.json()
if not r.ok:
    raise RuntimeError(f"{r.status_code} {answer['error']['code']}: {answer['error']['message']}")
print(answer)

{
  "error": {
    "code": "BAD_KEY",
    "message": "No key matches the one sent."
  }
}

Scopes

A key carries a scopes document, set in the portal's key editor: for each area of the API, which verbs it may use. The API has no endpoint for changing a key, on purpose.

• Each verb is "*" (all), or — for records — a list of dataset keys. An empty list is nothing.
• w is "change what is there", a is "make new ones": a key that feeds one dataset has no business creating others. On records, w also allows PUT, which replaces the whole dataset.
• Each endpoint on these pages names the scope it needs (and so does the OpenAPI document, as x-scope). A refusal is 403 OUT_OF_SCOPE naming the area, the action and, for records, the dataset as ref.
• A useful shape: a till key with records: {r: ["products"], w: ["transactions"]} and nothing else — it reads the catalogue, writes its sales, and cannot empty either.
• A key with no document at all (scopes: null) was made before scopes existed. It falls back to its scope: read may read everything, write may do everything. Editing it in the portal gives it a document.

Keys made before an area existed

curl "https://api.ardaform.net/v1/project" \
  -H "Authorization: Bearer $ARDA_KEY"

const res = await fetch('https://api.ardaform.net/v1/project', {
  headers: {
    Authorization: `Bearer ${process.env.ARDA_KEY}`
  }
})
const answer = await res.json()
if (!res.ok) throw new Error(`${res.status} ${answer.error.code}: ${answer.error.message}`)
console.log(answer)

import os
import requests

r = requests.get(
    "https://api.ardaform.net/v1/project",
    headers={"Authorization": f"Bearer {os.environ['ARDA_KEY']}"},
)
answer = r.json()
if not r.ok:
    raise RuntimeError(f"{r.status_code} {answer['error']['code']}: {answer['error']['message']}")
print(answer)

{
  "error": {
    "code": "OUT_OF_SCOPE",
    "message": "This key may not read project.",
    "area": "project",
    "action": "r"
  }
}

Expiry and revocation

• key.expires_on is a date, or null for never. A key works all through its expiry day (UTC) and answers 401 KEY_EXPIRED, carrying expired_on, after it.
• A revoked key answers 401 KEY_REVOKED. Revoking is in the portal, and it is immediate.

{
  "error": {
    "code": "KEY_EXPIRED",
    "message": "That key expired on 2026-10-05",
    "expired_on": "2026-10-05"
  }
}

Who this key is

curl "https://api.ardaform.net/v1/auth" \
  -H "Authorization: Bearer $ARDA_KEY"

const res = await fetch('https://api.ardaform.net/v1/auth', {
  headers: {
    Authorization: `Bearer ${process.env.ARDA_KEY}`
  }
})
const answer = await res.json()
if (!res.ok) throw new Error(`${res.status} ${answer.error.code}: ${answer.error.message}`)
console.log(answer)

import os
import requests

r = requests.get(
    "https://api.ardaform.net/v1/auth",
    headers={"Authorization": f"Bearer {os.environ['ARDA_KEY']}"},
)
answer = r.json()
if not r.ok:
    raise RuntimeError(f"{r.status_code} {answer['error']['code']}: {answer['error']['message']}")
print(answer)

{
  "key": {
    "name": "api npm test",
    "prefix": "af_••••••••",
    "scope": "write",
    "branch": null,
    "scopes": {
      "code": {
        "r": "*",
        "w": "*",
        "a": "*",
        "d": "*"
      },
      "datasets": {
        "r": "*",
        "w": "*",
        "a": "*",
        "d": "*"
      },
      "records": {
        "r": "*",
        "w": "*",
        "a": "*",
        "d": "*"
      },
      "files": {
        "r": "*",
        "w": "*",
        "a": "*",
        "d": "*"
      }
    },
    "expires_on": null,
    "created_at": "2026-08-21T08:49:42.652Z"
  },
  "project": {
    "slug": "api-test",
    "name": "API test",
    "status": "active"
  },
  "space": null,
  "account": {
    "name": "ArdaForm Test"
  },
  "limits": {
    "max_projects": 3,
    "max_devices": 10,
    "max_users": 1,
    "max_invited": 0,
    "max_datasets": 20,
    "max_spaces": 3,
    "storage_mb": 50,
    "console": false,
    "marketplace": true,
    "marketplace_fee": 20,
    "gui": true,
    "detect_priority": "normal",
    "support": "email",
    "webhooks": true,
    "webhook_endpoints": 2,
    "webhook_per_min": 60,
    "api_access": true,
    "api_keys": 2,
    "api_per_min": 600,
    "api_burst": 1200,
    "max_records_per_call": 10000,
    "max_bytes_per_call": 10485760
  }
}

The key scopes shape

Key scopes

What one API key may do, per area of the API. Null on a key made before scopes existed — which means it falls back to scope, NOT that it may do nothing.