Company sign-in

Company sign-in: the organization's own identity provider (Okta, Microsoft Entra ID or any OpenID Connect provider), the e-mail domains whose people sign in there, and the sign-in itself, which the passkey step follows.

POST /v1/auth/company/finish

Finish a company sign-in

Exchange the code the identity provider sent back for its ID token, check it (signature, issuer, audience, expiry, nonce, a verified address of one of the connection's domains) and sign the person in to that organization only. The answer is that of POST /v1/auth/google: passkey (then POST /v1/auth/passkey). Refused with 403 for a state that is too old or not this server's (company_sign_in_state), a token that does not hold (company_sign_in_refused) or an address that does not fit (company_sign_in_email).

Request body

application/json (required): CompanyFinish

Example request

curl -X POST "$ERP_URL/v1/auth/company/finish" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "c0d3-from-the-provider",
  "state": "eyJjIjoi.c2lnbmF0dXJl"
}'

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/company/start

Start a company sign-in

The identity provider's sign-in page for an address whose organization signs in with its own provider. It needs no credential and serves the web UI's sign-in page. The browser goes to url and comes back to the redirect URI with code and state for POST /v1/auth/company/finish. Refused with 403 (company_sign_in_none) when no organization that invited the address covers its domain.

Request body

application/json (required): CompanyStart

Example request

curl -X POST "$ERP_URL/v1/auth/company/start" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "lena.meier@acme.com"
}'

Responses

Example response (shape)

{
  "url": "string"
}

GET /v1/company-sign-in

Get the company sign-in

Whether company sign-in can be set up here, the redirect URI to register at the identity provider, and the organization's connection (its secret is never shown).

Example request

curl "$ERP_URL/v1/company-sign-in" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "available": true,
  "redirect_uri": "string",
  "connection": {
    "provider": "entra",
    "issuer": "https://acme.okta.com",
    "client_id": "string",
    "has_secret": true,
    "domains": [
      "string"
    ],
    "required": true,
    "last_used_at": "2026-09-21T09:30:00Z",
    "updated_at": "2026-09-21T09:30:00Z"
  }
}

PUT /v1/company-sign-in

Set up the company sign-in

Connect the organization's identity provider, or change the connection: the provider, its issuer (an Okta domain, an Entra tenant or an issuer URL), the app's client id and secret, the e-mail domains whose people sign in through it and whether they may sign in only through it. The provider's discovery document is read first: refused with 502 (company_sign_in_unreachable) when it does not answer for the issuer. Making it the only way in (required) is refused (company_sign_in_untried, 409) until somebody signed in through it. Every sign-in through it still ends with the person's passkey.

Request body

application/json (required): ConnectionInput

Example request

curl -X PUT "$ERP_URL/v1/company-sign-in" \
  -H "Authorization: Bearer $ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "client_id": "0oa1b2c3d4e5f6g7h8i9",
  "client_secret": "s3cr3t-of-the-okta-app",
  "domains": [
    "acme.com"
  ],
  "issuer": "acme.okta.com",
  "provider": "okta",
  "required": false
}'

Responses

Example response (shape)

{
  "provider": "entra",
  "issuer": "https://acme.okta.com",
  "client_id": "string",
  "has_secret": true,
  "domains": [
    "string"
  ],
  "required": true,
  "last_used_at": "2026-09-21T09:30:00Z",
  "updated_at": "2026-09-21T09:30:00Z"
}

DELETE /v1/company-sign-in

Remove the company sign-in

Remove the connection and its sealed secret: its people sign in with Google or a password again.

Example request

curl -X DELETE "$ERP_URL/v1/company-sign-in" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Schemas

CompanyFinish

CompanySignInSetup

CompanyStart

CompanyStartOut

ConnectionInput

ConnectionOut