Skip to content
bona fidedocs

Organizations, SSO & SCIM

Everything in Bona Fide belongs to an organization (a workspace): templates, envelopes, signing links, webhook endpoints, API keys and the plan. Every sign-up gets a personal organization, and people can be members of several. API keys act for the one organization that owns them.

Dashboard sessions act on the member’s active organization; an integration that calls the API with a session cookie can pick another one of the user’s organizations with the x-organization-id header.

Roles and permissions

Section titled “Roles and permissions”

Members have one role. Each role is a fixed set of permissions, and every endpoint checks a permission:

Role Permissions
owner Everything
admin Everything except billing:manage
sender envelope:read, envelope:send, envelope:void, template:read
template_manager template:read, template:write, template:publish, envelope:read
auditor envelope:read, template:read, audit:read
billing billing:manage

The full list of permissions is envelope:read, envelope:send, envelope:void, template:read, template:write, template:publish, org:manage, member:manage, sso:manage, apikey:manage, billing:manage and audit:read. API keys carry a subset of these as scopes.

Members, invitations, teams and organization branding are managed in the dashboard. Organization logos are uploaded with POST /v1/organization/logo (PNG, JPEG, SVG or WebP, up to 512 KB) from a dashboard session.

Single sign-on

Section titled “Single sign-on”

Owners and admins connect their identity provider themselves in Settings › Security › SSO, with SAML 2.0 or OIDC:

  1. Register the connection with your IdP’s metadata (the dashboard can fetch a SAML metadata URL for you).
  2. Verify your email domain with a DNS TXT record (the token starts with bona-fide-verify).
  3. Choose the settings: just-in-time provisioning (the first IdP login creates the member), the default role of new members, and enforcement: members with an email at the verified domain must sign in through the IdP; owners keep a break-glass login.
  4. Run a test login from the connection page before enforcing it.

Connection health (last login, logins in the last 30 days, certificate expiry) and an audit trail of every SSO and SCIM change (GET /v1/sso/audit) are shown on the same pages.

The sign-in page asks GET /v1/sso/discover?email=… whether an address uses company SSO; it is public and rate limited. When SSO is enforced, email-code and magic-link sign-in are refused for that domain.

SCIM directory sync

Section titled “SCIM directory sync”

With SCIM 2.0, your IdP creates, updates and deactivates members automatically. In Settings › Security › SCIM, create a bearer token (shown once) and give your IdP the SCIM base URL and the token. The base URL is https://api.bonafidesign.com/api/auth/scim/v2. Creating a new token replaces the previous one; revoking it stops provisioning.