Single sign-on (SSO)

SSO lets your team sign in to Encrata with your existing identity provider over OIDC. You add a connection for your email domain, verify you own that domain, then optionally require everyone on it to log in through your IdP. This guide walks through the full setup.

SSO is managed per workspace and only a workspace admin can configure it. Connections use OIDC - point them at any provider that publishes a standard discovery document (Okta, Entra ID, Google, Auth0, and others).

Before you start

Be a workspace admin

Only an admin can manage SSO. See Workspaces and teams for roles.

Create an OIDC application in your identity provider and note its issuer URL, client ID, and client secret.

Set up a connection

Create the connection

Send your issuer, client credentials, and the email domain it covers. Only issuer, client_id, client_secret, and email_domain are required.

curl -X POST https://developer.encrata.com/api/account/sso/connections \
  -H "Authorization: Bearer enc_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "issuer": "https://acme.okta.com",
    "client_id": "0oa1b2c3d4",
    "client_secret": "your-client-secret",
    "email_domain": "acme.com",
    "display_name": "Okta",
    "enforce_sso": true,
    "auto_provision": true
  }'

A 201 returns the connection. Note domain_verified is false and a verification_token is included for the next step. The client_secret is never returned.

{
  "id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "workspace_id": "b3f1c2a4-5d6e-4f70-8a1b-9c2d3e4f5a6b",
  "provider": "custom",
  "display_name": "Okta",
  "issuer": "https://acme.okta.com",
  "client_id": "0oa1b2c3d4",
  "scopes": "openid email profile",
  "email_domain": "acme.com",
  "enforce_sso": true,
  "auto_provision": true,
  "default_role": "member",
  "active": true,
  "domain_verified": false,
  "verification_token": "9f8e7d6c5b4a39281706",
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-15T10:00:00Z",
  "last_used_at": null,
  "connection_count": 0
}

Field	Type	Required	Description
`issuer`	string	Yes	OIDC issuer URL. Must be reachable over HTTPS and publish `/.well-known/openid-configuration`.
`client_id`	string	Yes	OIDC client ID from your IdP.
`client_secret`	string	Yes	OIDC client secret. Stored encrypted and never returned.
`email_domain`	string	Yes	Email domain this connection covers, e.g. `acme.com`.
`display_name`	string	No	Label shown on the login screen. Defaults to `SSO`.
`provider`	string	No	Provider tag. Defaults to `custom`.
`scopes`	string	No	OIDC scopes. Defaults to `openid email profile`.
`enforce_sso`	boolean	No	Require users on this domain to sign in through SSO. Defaults to `false`.
`auto_provision`	boolean	No	Create an account on first SSO login. Defaults to `true`.
`default_role`	string	No	Role given to auto-provisioned users. Defaults to `member`.

Verify domain ownership

A connection cannot log anyone in until you prove you own its domain. Add a DNS TXT record, then call verify.Create this record with your DNS provider:

Host	Value
`_encrata-sso.acme.com`	`encrata-sso-verify=<verification_token>`

Then confirm it:

curl -X POST https://developer.encrata.com/api/account/sso/verify-domain \
  -H "Authorization: Bearer enc_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f" }'

{ "domain_verified": true }

DNS changes can take time to propagate. If the record is not visible yet, the response returns domain_verified: false with the exact record_host and record_value to set. Wait and retry.

Test the connection

Check that your issuer’s discovery endpoint is reachable before you rely on it. Pass just the issuer.

curl -X POST https://developer.encrata.com/api/account/sso/test \
  -H "Authorization: Bearer enc_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "issuer": "https://acme.okta.com" }'

{ "success": true }

This endpoint always returns 200. Read the success field - a failure comes back as { "success": false, "error": "..." }.

Manage connections

List connections

Returns every SSO connection in your current workspace. Admin only.

curl https://developer.encrata.com/api/account/sso/connections \
  -H "Authorization: Bearer enc_your_key"

Update a connection

Send the connection id and the fields to change. Leave client_secret empty to keep the stored one. Admin only.

curl -X PUT https://developer.encrata.com/api/account/sso/connections \
  -H "Authorization: Bearer enc_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "issuer": "https://acme.okta.com",
    "client_id": "0oa1b2c3d4",
    "email_domain": "acme.com",
    "enforce_sso": true,
    "active": true
  }'

{ "status": "updated" }

Changing email_domain resets domain_verified to false. You will need to verify the new domain again.

Delete a connection

Pass the connection id as the id query parameter. Admin only.

curl -X DELETE "https://developer.encrata.com/api/account/sso/connections?id=c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer enc_your_key"

{ "status": "deleted" }

Account & team

Run your integration

Use cases

Integrations

AI tools

Agent-ready docs

auth.md

Single sign-on (SSO)

Before you start

Set up a connection

Manage connections

Next steps

Workspaces and teams

Authentication

​Before you start

​Set up a connection

​Manage connections

​Next steps

Workspaces and teams

Authentication

Before you start

Set up a connection

Manage connections

Next steps