Set up your own sign-in provider with a key¶

What an organisation's own sign-in provider is and whom it signs in is explained in Organisations and customers.

A key holding the management capability lets its own organisation's administrators sign in to the console through that organisation's identity provider: OpenID Connect, Google Workspace or Microsoft Entra ID. How to switch management on is in Administer your organisation with a key. Without it, every route on this page answers 404.

These routes cover the key's own organisation only. For an organisation below you, set it up in the console, or with a key you register in that organisation (Work inside an organisation below you).

Four rules hold whatever the provider:

• Nobody gets an account by signing in. Only someone the organisation has already invited as an administrator can sign in this way, matched on the email address the provider has verified.
• The provider's own second factor counts. If the provider asks for a code, the console does not ask for another.
• Someone who administers more than one organisation cannot sign in through any organisation's provider and signs in with a password.
• Removing a provider does not remove accounts. Anyone who also has a password keeps signing in with it.

Prove an email domain¶

A provider signs in only addresses in an email domain the organisation has proved it owns. Registering a provider for an organisation that has proved no domain is refused. Claim the domain first:

curl -s -X POST "$CORE_URL/organisation/email-domains" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"domain": "example.com"}'

The answer (201) names the TXT record that proves the domain:

{
  "object": "email_domain",
  "domain": "example.com",
  "verified": false,
  "proof_record_name": "_artific-challenge.example.com",
  "proof_record_value": "<random value>",
  "verified_at": null,
  "created_at": "2026-10-07T09:12:00Z"
}

With whoever runs your domain's DNS, publish a TXT record at proof_record_name holding proof_record_value. Then ask for the check:

curl -s -X POST "$CORE_URL/organisation/email-domains/example.com/verify" \
    -H "Authorization: Bearer $CORE_KEY"

The answer is the same domain with verified: true and verified_at filled in. Asking again for a domain already proved changes nothing. GET /organisation/email-domains lists every claimed domain in one page; an organisation claims at most fifty.

DELETE /organisation/email-domains/example.com gives the domain up (204). Your provider stops signing in anybody in it at once; accounts stay. If it answers 503, the claim stands; send the same request again later.

Allow the provider's hosts¶

The sign-in service talks to the provider on your organisation's behalf, so the organisation has to allow the provider's hosts before you register it:

Add each host with POST /organisation/allowed-hosts:

curl -s -X POST "$CORE_URL/organisation/allowed-hosts" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"host": "login.microsoftonline.com"}'

That answers 403 while the organisation above keeps key management to itself (Reserved key management); ask that organisation to allow the host.

Register a provider¶

PUT /organisation/sign-in-providers/{name} creates the provider of that name, or replaces it. The name is lowercase letters, digits and hyphens, at most 32 characters, with no hyphen at the start or end. It becomes part of the redirect address, so choose it once.

curl -s -X PUT "$CORE_URL/organisation/sign-in-providers/entra" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{
          "kind": "entra",
          "directory_id": "8c1f5a2e-3b4d-4e6f-9a0b-1c2d3e4f5a6b",
          "client_id": "<client id at your provider>",
          "client_secret": "<client secret at your provider>",
          "display_name": "Jansen"
        }'

kind decides which one other field the body carries:

client_id and client_secret are those of the client you created at your provider for this console; display_name is optional. The secret is never answered back. A replacement carries it again: a body without client_secret is refused.

The answer (200) is the provider as it now stands:

{
  "object": "sign_in_provider",
  "name": "entra",
  "kind": "entra",
  "issuer": "https://login.microsoftonline.com/8c1f5a2e-3b4d-4e6f-9a0b-1c2d3e4f5a6b/v2.0",
  "hosted_domain": null,
  "directory_id": "8c1f5a2e-3b4d-4e6f-9a0b-1c2d3e4f5a6b",
  "client_id": "<client id at your provider>",
  "display_name": "Jansen",
  "enabled": true,
  "sign_in_hint": "org.ten_8f2c41.entra",
  "redirect_uri": "https://login.example.com/realms/artific/broker/org.ten_8f2c41.entra/endpoint"
}

Register the redirect address and share the link¶

The answer carries two things you need next:

• Register redirect_uri on your client at the provider as an allowed redirect. The provider only starts working once that is done. If the provider asked for a redirect address before you could create the client, create it with a placeholder, register the provider here, and replace the placeholder with redirect_uri.
• sign_in_hint makes the sign-in link. The ordinary sign-in page lists no organisation's providers, so give your administrators the console's sign-in address with the hint in it: https://<console address>/en/login?provider=org.ten_8f2c41.entra (or /nl/ for the Dutch console). Opening it sends them straight to your provider (Sign in).

Read, change and remove providers¶

Every registration and removal is a management event on the organisation's trail (Management events), without the secret.