Avura

API tokens

Mint, list, and revoke bearer tokens — including subtree-contained delegation.

API tokens are the bearer credentials described in Authentication. Manage them from Settings → API tokens or programmatically through this API. The plaintext secret is returned exactly once, on creation — only a SHA-256 hash is stored.

/api/tokens

GET/api/tokens

List active tokens. Org admins see every token in the organization; other members see only tokens they created. A zone-pinned caller sees only tokens pinned inside its own subtree.

POST/api/tokens

Mint a token. Body: name (required), scope (read | write, default read), domainId (optional zone pin), expiresInDays (1–365, optional). Returns 201 with the plaintext token and a summary.

/api/tokens/:id

DELETE/api/tokens/:id

Revoke a token immediately. Org admins revoke any org token; other members only tokens they created; zone-pinned callers only tokens pinned inside their subtree.

Who can mint what:

  • Org owners and admins mint org-wide tokens (no domainId) or tokens pinned to any domain.
  • Zone managers mint tokens pinned to a domain they manage — including any of its subzones. Requesting no pin returns 403 domain_pin_required.
  • Scope is fixed at mint time — read tokens may only call GET/HEAD/OPTIONS, write tokens may call every method. A read token can never mint (POST is a write).
  • Expiry is optional — omit expiresInDays for a non-expiring token, or set 1–365 days. Expired and revoked tokens fail with 401 invalid_token.
curl -X POST https://avura.work/api/tokens \
  -H "Authorization: Bearer avk_5f2c1e9a..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "external-dns dev.example.com",
    "scope": "write",
    "domainId": "dom_dev",
    "expiresInDays": 90
  }'

A write token pinned to a domain can itself call this API and delegate: it mints, lists, and revokes child tokens without any human session. Delegation is strictly contained:

  • A pinned caller must always pin the child token — even when its user is an org admin. Requests without domainId return 403 domain_pin_required.
  • The child pin must be the caller's own domain or one of its descendants. Anything outside the subtree returns 403 forbidden.
  • A delegated token never outlives its issuer: the child's expiry is clamped to the issuing token's expiry, including when no expiry was requested.
  • Listing and revocation are filtered the same way — a pinned caller never sees or revokes org-wide tokens or tokens pinned outside its subtree.

Combined with POST /api/domains/:id/subzones, automation holding a subzone token can spawn a nested subzone and hand out an isolated credential for it:

# 1. the subzone token creates a nested subzone
curl -X POST https://avura.work/api/domains/$SUBZONE_ID/subzones \
  -H "Authorization: Bearer $SUBZONE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "app"}'

# 2. ...and mints a write token that only reaches the new subtree
curl -X POST https://avura.work/api/tokens \
  -H "Authorization: Bearer $SUBZONE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "app zone", "scope": "write", "domainId": "<new subzone id>"}'