Getting started

Register, complete a profile, activate

This walks through the full self-service flow against the live instance at https://directory.open.dev.br. Every request below is real — there is no separate sandbox environment; registering here creates an institution in Pending status until it passes functional validation.

01 Register

POST /register is public and rate-limited by IP. It creates the institution (status Pending, never listed at /participants yet) and its first admin user, and returns a session token — shown once.

curl -X POST https://directory.open.dev.br/register \
  -H "Content-Type: application/json" \
  -d '{
    "organisationName": "Example Bank",
    "adminEmail": "admin@example.com",
    "adminPassword": "a-password-of-at-least-12-chars"
  }'

{
  "organisationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sessionToken": "kuqRrmsjEllTJlH8OAHsPj6NhNq-ax2gras0IANQRgE",
  "status": "Pending"
}

02 Verify the admin email

A verification link is emailed to adminEmail. Verifying it is a precondition for activation — GET /verify-email consumes the token in the link.

curl "https://directory.open.dev.br/verify-email?token=<token-from-the-email>"

03 Complete the profile

Set a jwksUri and register at least one authorisation server with a dcrRegistrationUri — both are checked in the next step. Authenticate with the session token from step 1.

curl -X PUT https://directory.open.dev.br/admin/institutions/{institutionId} \
  -H "Authorization: Bearer {sessionToken}" \
  -H "Content-Type: application/json" \
  -d '{ "jwksUri": "https://example-bank.test/jwks.json" }'

curl -X POST https://directory.open.dev.br/admin/institutions/{institutionId}/authorisation-servers \
  -H "Authorization: Bearer {sessionToken}" \
  -H "Content-Type: application/json" \
  -d '{ "dcrRegistrationUri": "https://example-bank.test/register" }'

04 Activate

POST .../activate runs the functional validation described in Registration & validation — a real mTLS call to dcrRegistrationUri and a real fetch of jwksUri. It's synchronous, idempotent, and safe to retry.

curl -X POST https://directory.open.dev.br/admin/institutions/{institutionId}/activate \
  -H "Authorization: Bearer {sessionToken}"

On success, the institution's status flips to Active and it appears in GET /participants.