Help
Set up SSO and SCIM for your organization
Tested with:Databasezy API v1 · zb CLI 0.1
Team and Enterprise organizations can let members sign in to the portal through their company’s identity provider
(OIDC or SAML), require it for everyone at a verified email domain, and provision members and teams automatically
with SCIM. Setup is done through the API today: the Configure SAML button on the Members page is not active yet.
Every step needs the org:manage permission (owners and admins).
402 plan_limit: “SSO and SCIM provisioning need the Team or Enterprise plan”
Section titled “402 plan_limit: “SSO and SCIM provisioning need the Team or Enterprise plan””SSO, domain enforcement and SCIM are part of Team and Enterprise. On Free or Solo every SSO route answers this error. See Changing plans.
Step 1: add a connection
Section titled “Step 1: add a connection”Register Databasezy as an application in your identity provider, then add the connection. Changes need a session that passed two-factor authentication if your organization requires it.
# OIDC: active at oncezb api POST /v1/orgs/{org}/sso/connections -d '{ "kind": "oidc", "name": "Okta", "issuer_url": "https://example.okta.com", "client_id": "...", "client_secret": "...", "default_role": "member"}'
# SAML: give the IdP metadata URL (or the XML in idp_metadata_xml)zb api POST /v1/orgs/{org}/sso/connections -d '{ "kind": "saml", "name": "Entra ID", "idp_metadata_url": "https://login.example.com/federationmetadata.xml"}'The response includes callback_url: register it at your identity provider as the redirect URI (OIDC) or the ACS
URL (SAML). default_role is the organization role for people who arrive through SSO or SCIM without a group
mapping; it defaults to member (project access only).
A SAML connection stays pending until it is registered with our SAML bridge. If it does not become active,
read its last_error:
zb api GET /v1/orgs/{org}/sso/connectionsStep 2: verify your email domain
Section titled “Step 2: verify your email domain”zb api POST /v1/orgs/{org}/sso/domains -d '{"domain": "example.com"}'The answer names a TXT record to create: _databasezy-challenge.example.com with the value
databasezy-verification=<token>. After it is published in DNS, verify it:
zb api POST /v1/orgs/{org}/sso/domains/<domain_id>/actions/verifyIf verification fails, check that the record name and value match exactly and that DNS has propagated, then retry. A domain can be verified by only one organization.
Step 3: enforce SSO (optional)
Section titled “Step 3: enforce SSO (optional)”zb api PATCH /v1/orgs/{org}/sso/domains/<domain_id> -d '{"enforce_sso": true}'From then on, members whose email is at that domain must reach the organization through your identity provider. Owners are exempt, so you cannot lock yourself out. Enforcement needs a verified domain and an active connection.
403 sso_required: “requires signing in with its identity provider”
Section titled “403 sso_required: “requires signing in with its identity provider””Your organization enforces SSO for your email domain and you signed in another way (for example with a password). Sign out, then sign in through your company’s identity provider. If you do not know how, ask your organization’s admin.
Step 4: SCIM provisioning (optional)
Section titled “Step 4: SCIM provisioning (optional)”SCIM lets Okta, Entra ID and other providers create, update and remove members and teams for you.
-
Create a token. It starts with
zbscim_and is shown once; store it in your identity provider straight away.shell zb api POST /v1/orgs/{org}/sso/scim-tokens -d '{"name": "okta"}' -
In your identity provider, set the SCIM base URL to
https://api.databasezy.com/scim/v2and use the token as the bearer token. -
Push users and groups. Users become members with the connection’s default role. Groups become teams; set what each group grants with
zb api PATCH /v1/orgs/{org}/sso/scim-groups/<group_id> -d '{"team_role": "developer", "org_role": "developer"}'. When a person is in several mapped groups, the most privileged one wins.
Deactivating or deleting a user in your identity provider removes their membership and team memberships. Owners are
never changed by SCIM. Revoke a token you no longer use with
zb api DELETE /v1/orgs/{org}/sso/scim-tokens/<token_id>.
A SCIM-provisioned person cannot get in
Section titled “A SCIM-provisioned person cannot get in”A user created by SCIM has no Databasezy password. They claim the account the first time they sign in through SSO, or with a verified email at your domain. If the email already belongs to an existing Databasezy account, linking it needs your organization to have verified that email’s domain.
Still stuck?
Section titled “Still stuck?”Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support
ticket from the portal (Help → Open a ticket, category account) and include the connection id and kind, the
connection’s status and last_error, the domain, your identity provider, the exact error text and the time in UTC.
Never paste client secrets, SCIM tokens, passwords, API keys or patient data (PHI) into a ticket. See
How to get help.