Docs For organizations

Getting started

Everything an organization does in the directory goes through the organization console at svid.io/console/, which uses the same API documented in the API reference. This page covers the first three steps: sign in, passkey, organization.

Open /console/ and choose GitHub or Google. Sign-in uses the provider's authorization-code flow with PKCE; the directory records the verified email address the provider returns. GET /auth/providers lists the providers a deployment has configured.

The session lives in a __Host-art_session cookie (HttpOnly, Secure, SameSite=Lax) that lasts 12 hours. Staging also offers a test identity provider; it never exists in production.

Set up a passkey

A sign-in alone cannot change anything. The first time you sign in, the console asks you to create a passkey on your device; after that, every console session is confirmed with it. Until the passkey assertion is done, every mutation answers 401 unauthenticated ("Passkey verification required.").

The same passkey is your step-up check. Sensitive actions (registering or rotating an issuer, delegations, membership and role changes, service tokens, claim withdrawal and appeals) need a passkey assertion that is at most 300 seconds old. When it is older, the API answers 401 step_up_required; the console asks you to touch your passkey again and retries. See API access.

Registering an additional passkey later needs a passkey-verified session and a fresh step-up.

Create your organization

On the console dashboard choose Add organization, or call POST /v1/organizations:

Field	Rules
`legal_name`	Required. 1 to 200 characters, trimmed and NFC-normalized, no control or bidirectional-override characters.
`jurisdiction`	Required. An ISO 3166-1 alpha-2 country, optionally with an ISO 3166-2 subdivision: `US` or `US-DE`.
`registration_reference`	Optional, up to 100 characters: your company or registry number.

The organization starts as a draft and you become its owner. Its identity is not verified yet: that happens through review, as part of your first domain claim. A person can create at most 5 organizations in a rolling 24 hours. Platform staff accounts (reviewers and operators) cannot create or join organizations.

bash

curl https://svid.io/v1/organizations \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Origin: https://svid.io" \
  -H "Cookie: __Host-art_session=<session>" \
  -H "x-art-csrf: <csrf_token from GET /auth/session>" \
  -H "Idempotency-Key: 7f3c1b52-9d44-4a0e-8f21-0a6e5b9d3c77" \
  -d '{"legal_name":"Example Payments, Inc.","jurisdiction":"US-DE","registration_reference":"1234567"}'

Most organizations use the console for this step. The request shows what every session-authenticated mutation needs: the session cookie, an Origin equal to the directory origin, the x-art-csrf token and an Idempotency-Key.

Invite your team

Owners invite people by email from the organization page (POST /v1/organizations/{id}/invitations, step-up). Nobody becomes a member until they accept, and accepting also needs a fresh passkey check. Invitations expire after 7 days, and the directory stores only a keyed hash of the address.

Role	Can
`organization_owner`	Everything below, plus members, invitations, service tokens, delegations, claim withdrawal and appeals
`issuer_administrator`	Register, rotate and withdraw issuer bindings
`domain_administrator`	File claims, run DNS challenges, submit evidence. Cannot authorize issuers.
`viewer`	Read the organization's records

The last owner can never be demoted or removed. Demoting an owner revokes the service tokens they created for the organization.

Claim a domain: publish a DNS TXT record and start the review.

Sign in#

Set up a passkey#

Create your organization#

Invite your team#

Next#

Sign in

Set up a passkey

Create your organization

Invite your team

Next