Users

People who sign in to the web UI, their roles, and the UI's sign-in endpoints.

GET /v1/auth/config

Get the sign-in settings

What the web UI's sign-in page needs: the Google OAuth client id (google_client_id, null when Google sign-in is not configured), where people without a Google account sign in with a password (password_sign_in, null when not configured) and whether the development login is on. It needs no credential and is not for API-key clients, which sign in with their key.

Example request

curl "$ERP_URL/v1/auth/config" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "google_client_id": "string",
  "password_sign_in": {
    "api_key": "string",
    "project": "string"
  },
  "dev_login": true
}

POST /v1/auth/google

Sign in with Google

Exchange a Google ID token for a web UI session cookie.

This endpoint serves the web UI session and is not for API-key clients: a script authenticates with an API key (Authorization: Bearer <key>), never with this call. The caller must have been invited (POST /v1/users). On success the answer is passkey: every sign-in also needs the person's passkey (ADR-0101). The browser touches it, or creates the first one, with the options in passkey, and sends the answer to POST /v1/auth/passkey, which sets the erp_session cookie (HttpOnly, SameSite=Strict). When the address belongs to several organizations the answer is choose_organization with the list: repeat the call with the chosen org_id. No cookie is set by this call. Refused with 403 for an invalid token, a person who is not invited, a domain that may not sign in, or an org_id that is not theirs; with 422 when Google sign-in is not configured on the server.

Request body

application/json (required): GoogleLogin

Example request

curl -X POST "$ERP_URL/v1/auth/google" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "credential": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ij..."
}'

Responses

Example response (shape)

{
  "status": "choose_organization",
  "organizations": [
    {
      "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "org_name": "string",
      "test_organization": false,
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "expires_at": "2026-09-21T09:30:00Z",
  "passkey": {
    "setup": true,
    "options": {}
  }
}

POST /v1/auth/logout

Sign out of the web UI

End the web UI session whose cookie accompanies the request and clear the cookie. It serves the web UI and is not for API-key clients: with an API key there is no session to end and nothing happens. The response has no body.

Example request

curl -X POST "$ERP_URL/v1/auth/logout" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

GET /v1/auth/organizations

List my organizations

The organizations the signed-in person may switch to, their current one included, as sign-in lists them (test_organization marks a test copy or demo). Only for a web UI session: an API key answers 403, as it belongs to one organization.

Example request

curl "$ERP_URL/v1/auth/organizations" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

[
  {
    "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "org_name": "string",
    "test_organization": false,
    "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
]

POST /v1/auth/passkey

Sign in with a passkey

The second step of every sign-in to the web UI (ADR-0101): the browser's answer to the passkey question of POST /v1/auth/google or POST /v1/auth/password. For a person without a passkey the answer creates their first (name names it); otherwise it is a touch of one of theirs. On success the answer is signed_in and the erp_session cookie is set (HttpOnly, SameSite=Strict). The question is valid once and for five minutes. Refused with 403 for an answer that does not verify (passkey_refused), a question that is used or expired (passkey_expired, sign in again) or a person who may no longer sign in; with 409 for a passkey already registered. A passkey made at the site's former address (it moved) is answered passkey once more: create the passkey of this address with that question and send the answer here; the session starts with it. Refusals count against the client address like refused sign-ins (429 past the limit). It serves the web UI and is not for API-key clients.

Request body

application/json (required): PasskeyAnswer

Example request

curl -X POST "$ERP_URL/v1/auth/passkey" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "credential": {
    "id": "q2Vx...",
    "rawId": "q2Vx...",
    "response": {
      "authenticatorData": "SZYN...",
      "clientDataJSON": "eyJ0..."
    },
    "type": "public-key"
  }
}'

Responses

Example response (shape)

{
  "status": "choose_organization",
  "organizations": [
    {
      "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "org_name": "string",
      "test_organization": false,
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "expires_at": "2026-09-21T09:30:00Z",
  "passkey": {
    "setup": true,
    "options": {}
  }
}

POST /v1/auth/password

Sign in with a password

Exchange the ID token of an e-mail and password sign-in at Google Identity Platform for a web UI session cookie, for people without a Google account (ADR-0037).

The browser sends the address and password to Google (accounts:signInWithPassword with the password_sign_in.api_key of GET /v1/auth/config), never to this server; Google keeps the password and refuses repeated wrong ones. This call takes the idToken Google returned. It serves the web UI and is not for API-key clients. The answers are those of POST /v1/auth/google: passkey (then POST /v1/auth/passkey), or choose_organization. Refused with 403 for an invalid token, an address that is not verified, a person who is not invited, a domain that may not sign in, or an org_id that is not theirs; with 409 when password sign-in is not configured. Failed sign-ins count against the client address (429 past the limit).

Request body

application/json (required): PasswordLogin

Example request

curl -X POST "$ERP_URL/v1/auth/password" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "credential": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ij..."
}'

Responses

Example response (shape)

{
  "status": "choose_organization",
  "organizations": [
    {
      "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "org_name": "string",
      "test_organization": false,
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "expires_at": "2026-09-21T09:30:00Z",
  "passkey": {
    "setup": true,
    "options": {}
  }
}

POST /v1/auth/step-up

Touch your passkey again

Check the browser's answer to POST /v1/auth/step-up/options and note the touch on the session: steps that ask for a fresh touch work for five minutes from now. 403 for an answer that does not verify, a used or expired question, another session's question or an API key.

Request body

application/json (required): PasskeyAnswer

Example request

curl -X POST "$ERP_URL/v1/auth/step-up" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "credential": {
    "id": "q2Vx...",
    "rawId": "q2Vx...",
    "response": {
      "authenticatorData": "SZYN...",
      "clientDataJSON": "eyJ0..."
    },
    "type": "public-key"
  }
}'

Responses

Example response (shape)

{
  "passkey_at": "2026-09-21T09:30:00Z"
}

POST /v1/auth/step-up/options

Ask for a fresh passkey touch

The question for a fresh touch of the signed-in person's passkey, which a risky step asks for (403 passkey_step_up with within_minutes): touch it in the browser with these options, send the answer to POST /v1/auth/step-up, then repeat the step. Only for a web UI session (403 for an API key).

Example request

curl -X POST "$ERP_URL/v1/auth/step-up/options" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "setup": true,
  "options": {}
}

POST /v1/auth/switch

Switch organization

Move the signed-in person to another of their organizations (GET /v1/auth/organizations) without signing in again, for example from a test copy back to the real organization. The current session ends and a new one starts in org_id, checked as a sign-in with the same account would be: the answer and the erp_session cookie are those of signed_in. The new session ends when the current one would have: a switch never extends a sign-in. Refused with 403 for an org_id that is not theirs and for an API key, and with 409 for the organization the person is already in. A suspended organization may still be left this way. Recorded as user.login with via: switch and the organization left (from_org).

Request body

application/json (required): OrganizationSwitch

Example request

curl -X POST "$ERP_URL/v1/auth/switch" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "org_id": "3f0c2a9e-5b7d-4e1a-9c8b-2d6f4a1e7b30"
}'

Responses

Example response (shape)

{
  "status": "choose_organization",
  "organizations": [
    {
      "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "org_name": "string",
      "test_organization": false,
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "copy_of": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "expires_at": "2026-09-21T09:30:00Z",
  "passkey": {
    "setup": true,
    "options": {}
  }
}

GET /v1/me/passkeys

List my passkeys

The signed-in person's passkeys, oldest first. They open every organization the person is a user of. Only for a web UI session (403 for an API key).

Example request

curl "$ERP_URL/v1/me/passkeys" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "created_at": "2026-09-21T09:30:00Z",
    "last_used_at": "2026-09-21T09:30:00Z",
    "backed_up": true
  }
]

POST /v1/me/passkeys

Add a passkey

Record the passkey the browser created for POST /v1/me/passkeys/options, named name. Needs a passkey touch within five minutes (403 passkey_step_up); 403 for an answer that does not verify or a used or expired question; 409 for a passkey already registered. Recorded as a security event (passkey.add).

Request body

application/json (required): PasskeyAnswer

Example request

curl -X POST "$ERP_URL/v1/me/passkeys" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "credential": {
    "id": "q2Vx...",
    "rawId": "q2Vx...",
    "response": {
      "authenticatorData": "SZYN...",
      "clientDataJSON": "eyJ0..."
    },
    "type": "public-key"
  }
}'

Responses

Example response (shape)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "created_at": "2026-09-21T09:30:00Z",
  "last_used_at": "2026-09-21T09:30:00Z",
  "backed_up": true
}

POST /v1/me/passkeys/options

Start adding a passkey

The question to create one more passkey, for another device: create it in the browser with these options and send the answer to POST /v1/me/passkeys. Needs a passkey touch within five minutes (403 passkey_step_up); only for a web UI session.

Example request

curl -X POST "$ERP_URL/v1/me/passkeys/options" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "setup": true,
  "options": {}
}

DELETE /v1/me/passkeys/{passkey_id}

Remove a passkey

Remove one of the signed-in person's passkeys (a lost or replaced device). Needs a passkey touch within five minutes (403 passkey_step_up); 409 for the last one (passkey_last: add another first); 404 for a passkey that is not theirs. Recorded as a security event (passkey.remove). The response has no body.

Parameters

Example request

curl -X DELETE "$ERP_URL/v1/me/passkeys/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

GET /v1/people

List the people to choose from

The active people of the organization (id, email, name) ordered by name, to choose the owner of a deal or a close task from. Any credential with the read scope may list them; invitations, scopes and their management are GET /v1/users (admin scope).

Example request

curl "$ERP_URL/v1/people" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "string",
    "name": "string"
  }
]

GET /v1/users

List users

The people of the organization (invited, active or disabled) ordered by email, with their scopes. Only a human with the admin scope may list them (403 otherwise).

Example request

curl "$ERP_URL/v1/users" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "string",
    "name": "string",
    "scopes": [
      "string"
    ],
    "status": "string",
    "created_at": "2026-09-21T09:30:00Z",
    "last_login_at": "2026-09-21T09:30:00Z",
    "locale": "string",
    "access_until": "2026-09-21T09:30:00Z"
  }
]

POST /v1/users

Invite a user

Invite a person by email; they sign in to the web UI with the Google account of that address, or, without one, with the address and a password, which activates the user. When password sign-in is configured, Google also e-mails them the link that sets their password (as POST /v1/users/{user_id}/password-email), except to an address of the deployment's Google Workspace domains, whose people sign in with Google. The access is a role preset (viewer by default) or an explicit list of scopes, which wins when both are sent. Only a human with the admin scope may invite (403 otherwise); 409 when the address is already a user of this organization; 422 for an unknown scope; 502 when Google refuses the e-mail (nobody is invited, the request can be repeated). The new user has status invited.

An external auditor (the auditor role) is invited with access_until, the moment their access ends (422 access_until_missing without it): they read everything and change nothing, and every request they make goes to the access log (GET /v1/access-log).

Request body

application/json (required): InviteInput

Example request

curl -X POST "$ERP_URL/v1/users" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "anna.keller@example.com",
  "name": "Anna Keller",
  "role": "accountant"
}'

Responses

Example response (shape)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "string",
  "name": "string",
  "scopes": [
    "string"
  ],
  "status": "string",
  "created_at": "2026-09-21T09:30:00Z",
  "last_login_at": "2026-09-21T09:30:00Z",
  "locale": "string",
  "access_until": "2026-09-21T09:30:00Z",
  "password_email_sent": true
}

PATCH /v1/users/{user_id}

Update a user

Change a user's name, access or status. Send a role preset or a list of scopes, not both (422); only the fields sent change. Setting the status to disabled also ends the user's sessions. access_until moves the end of the user's access (null removes it, except for an external auditor). You cannot remove your own admin scope, disable yourself or set an end to your own access (409). Only a human with the admin scope may do this (403 otherwise); an unknown user answers 404.

Parameters

Request body

application/json (required): UserUpdate

Example request

curl -X PATCH "$ERP_URL/v1/users/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "controller"
}'

Responses

Example response (shape)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "string",
  "name": "string",
  "scopes": [
    "string"
  ],
  "status": "string",
  "created_at": "2026-09-21T09:30:00Z",
  "last_login_at": "2026-09-21T09:30:00Z",
  "locale": "string",
  "access_until": "2026-09-21T09:30:00Z"
}

POST /v1/users/{user_id}/passkeys/reset

Reset a user's passkeys

For a person who lost every device with a passkey: remove their passkeys and end their sessions; their next sign-in creates a new first passkey. Only a human administrator may do this, with a passkey touch within five minutes (403 passkey_step_up), and not for themselves (409). For a person who is also a user of another organization (other than this one's test copies) it answers 409 passkey_reset_elsewhere: their passkeys open that organization too, so the platform's operator resets them. 404 for an unknown user. Recorded in the audit trail (user.passkey_reset) and as a security event (passkey.reset).

Parameters

Example request

curl -X POST "$ERP_URL/v1/users/3fa85f64-5717-4562-b3fc-2c963f66afa6/passkeys/reset" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "removed": 1
}

POST /v1/users/{user_id}/password-email

E-mail a user a link to set their password

Have Google e-mail the user a link that sets the password of their account at Google Identity Platform, for a person without a Google account (ADR-0037). It creates the account when there is none, sets a first password and resets a forgotten one alike; an existing password keeps working until the link is used. Google sends the e-mail; the ERP never sees the password. Only a human with the admin scope may do this (403 otherwise); 404 for an unknown user; 409 for a disabled user or when password sign-in is not configured; 502 when Google refuses. Recorded in the audit trail (user.password_email).

Parameters

Example request

curl -X POST "$ERP_URL/v1/users/3fa85f64-5717-4562-b3fc-2c963f66afa6/password-email" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "email": "string"
}

Schemas

AuthConfig

GoogleLogin

InviteInput

InvitedUser

OrganizationSwitch

PasskeyAnswer

PasskeyOut

PasskeyReset

PasswordEmailSent

PasswordLogin

PasswordSignIn

StepUpDone

UserOut

UserUpdate