Overview

Administer an organization over REST — clients, pages, domains, tenants, members, webhooks.

Everything the console does, it does through the /organizations routes documented in this tab, one page per endpoint. Hosts, the OAuth endpoints and discovery are in the Client API.

Who can call it

Every route here takes a user access token, Authorization: Bearer …. The token is checked against the keys of the org whose host the request arrives on, so the host and the token have to match. There are two ways in:

The {org} in the path has to name an org the token can manage: any org you are a member of with a console token, the host’s org with an org token. Any other org, whether it exists or not, gets 404 not_found.

With a console token you don’t need to switch orgs to manage one: GET /organizations lists them, and you name the one you want in the path.

The examples in this tab use a console token on https://loginwith.loginwith.dev.

Roles

Being let in is not enough on its own. Your role in the org decides what you can do:

Each endpoint page states its own rule under Authorization.

Conventions

• Ids carry a prefix: org_, cli_, pge_, kit_, dom_, tnt_, usr_, lbl_, whk_, mfa_. An id with the wrong prefix in a path is a 404, the same as an id that does not exist.
• {org} accepts either form: org_… is read as an id, anything else as a slug.
• Bodies are JSON. An unknown key is 400 invalid_request, and so is a value that fails validation. The error names the first bad field.
• PATCH: the body is the mask. The keys you send are the fields that change, and keys you leave out stay as they are. There is no ?mask= parameter. An empty body is 400 (“nothing to change”). Only the fields an endpoint page marks clearable can be cleared.
• Errors come back as { "error": "…", "error_detail": "…" }, where error is a stable code (invalid_request, forbidden, not_found, conflict, …) and error_detail says what went wrong in words. A request with no usable token is a 401.
• Lists are not paginated, and return a plain JSON array. The exception is the event log.
• Deletes answer 204 with no body. Deleting something still in use is a 409 conflict that says what is using it.
• Secrets are shown once. A client secret or webhook secret appears only in the response that creates it.

# The orgs this console token can manage
curl https://loginwith.loginwith.dev/organizations \
  -H "Authorization: Bearer $TOKEN"

# Create a confidential client in acme
curl -X POST https://loginwith.loginwith.dev/organizations/acme/clients \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme backend","confidential":true,"redirect_uris":["https://app.acme.com/lgw/callback"]}'

Resources