Registry API — bRRAIn Docs

Programmatic API for the ID Registry — claim a bRRAInUserID, manage your profile, query verification status.

Registry API

The Registry API exposes the ID Registry — bRRAIn's identity-of-record service — for programmatic use. It's how applications outside bRRAIn verify a user's bRRAInUserID, certifications, or vanity URL.

Base path

https://id.brrain.io/api

Lookups (public, unauthenticated)

Resolve a bRRAInUserID

GET /resolve/{handle}

Where {handle} is the vanity URL slug (e.g. faruq-hunter) or the canonical 5-part hex ID.

Returns:

{
  "handle": "faruq-hunter",
  "canonical_id": "BBI-AB12-CD34-EF56-7890",
  "display_name": "Faruq Hunter",
  "verified": true,
  "certifications": [
    {
      "slug": "bRRAInOps-operations-controller",
      "issued_at": "2026-03-15",
      "expires_at": null,
      "verifying_url": "https://id.brrain.io/cert/..."
    }
  ],
  "vanity_url": "https://id.brrain.io/u/faruq-hunter"
}

If the handle isn't claimed, returns 404.

Verify a verification chip

POST /verify/chip
Content-Type: application/json

{
  "chip_id": "chp_8a2b3c...",
  "issued_at_signature": "..."
}

Returns whether the chip is valid, who it identifies, and what it certifies.

Used by recipients of a chip-bearing artifact (resume, contract, claim) to confirm the chip wasn't forged.

GET /search?q=...

Looks up by name (with permission of the indexed user — opt-in only).

Profile management (authenticated)

Authenticated as the user who owns the bRRAInUserID.

Claim a handle

POST /handles
Content-Type: application/json

{
  "handle": "your-desired-handle"
}

Claims the handle if available. Handles are alphanumeric + dashes, 3–30 characters, lowercased.

Update profile

PUT /profile
Content-Type: application/json

{
  "display_name": "...",
  "bio": "...",
  "avatar_url": "...",
  "links": [
    { "label": "GitHub", "url": "..." },
    ...
  ]
}

Vanity site builder

PUT /vanity-site
Content-Type: application/json

{
  "sections": [
    { "type": "about", "body": "..." },
    { "type": "projects", "items": [ ... ] },
    ...
  ],
  "theme": "minimal-dark"
}

Builds your one-page site at id.brrain.io/u/{handle}.

List your certifications

GET /me/certifications

Pulls from the Learn surface. Each entry includes verification URLs.

Issue a chip

POST /chips
Content-Type: application/json

{
  "scope": "resume",
  "expires_at": "2027-05-13T00:00:00Z",
  "scope_data": {
    "purpose": "Job application",
    "audience": "any"
  }
}

Returns:

{
  "chip_id": "chp_...",
  "verify_url": "https://id.brrain.io/verify/chp_...",
  "qr_code_svg": "...",
  "html_embed": "..."
}

Chips are short-lived signed tokens. Embed the HTML or QR in the artifact you want to authenticate.

Webhooks

  • registry.handle_claimed
  • registry.profile_updated
  • registry.certification_added
  • registry.chip_used

Errors

  • handle_unavailable — already taken.
  • handle_invalid — fails the validation rules.
  • handle_reserved — name is on the reserved-list (we keep some for system use).
  • chip_expired
  • chip_revoked
  • chip_invalid_signature

Where to next