Organizations — Core API

Lists all organizations within an issuer.

Organizations are groups of users, commonly used for multi-tenancy where each customer or team is an organization.

Use cases for organizations:

• Multi-tenant SaaS - Each customer is an organization with their own users
• Team workspaces - Group users into teams with shared permissions
• B2B applications - Manage enterprise customers and their employees

Creates a new organization within an issuer.

Organizations are containers for grouping users, typically representing:

• Customer accounts in a multi-tenant application
• Teams or departments within a company
• Projects or workspaces

After creating an organization:

1. Add members using the Add Organization Member endpoint
2. Configure roles and permissions as needed
3. Optionally set up API keys for service-to-service authentication

Custom metadata: Use the metadata field to store application-specific data like billing tier, feature flags, or external system IDs.

Retrieves the full details of an organization by its ID.

Returns complete organization information including:

• Profile - Name, display name, description, logo
• Settings - Custom configuration and metadata
• Statistics - Member count and other aggregates
• Timestamps - Creation and last update times

Updates an organization's details.

All fields in the request body are optional - only include the fields you want to change.

Updatable fields:

• name - Internal identifier (must be unique within the issuer)
• display_name - User-facing name shown in UIs
• description - Optional description
• logo_url - URL to the organization's logo
• metadata - Custom key-value data (merged with existing metadata)

Metadata updates: Metadata is merged, not replaced. To remove a key, set it to null.

Deletes an organization and removes all its members.

What happens on deletion:

• All organization API keys are revoked before anything else is removed — if revocation fails, the deletion is aborted and can be retried
• All member associations are removed
• Organization metadata is deleted
• Users are NOT deleted (they remain in the issuer)

Before deleting:

1. Consider exporting organization data if needed for compliance
2. Notify affected users if appropriate

Note: This is a permanent operation. Unlike users and issuers, organizations do not have a soft-delete grace period.

Lists all members of an organization with their roles and status.

Each membership includes:

• User reference - The user ID and basic profile info
• Role - The member's role within the organization (e.g., owner, admin, member)
• Scopes - Fine-grained permissions granted to this member
• Status - Active, suspended, or removed

Use the status filter to find suspended members or audit removed memberships.

Use the scope filter to find all members who have a specific effective scope (including scopes inherited from groups).

Adds a user as a member of an organization.

The user must already exist in the issuer. This endpoint creates the membership association with the specified role and permissions.

Roles: Define roles that make sense for your application. Common patterns:

• owner - Full control, can delete the organization
• admin - Can manage members and settings
• member - Standard access

Scopes: Use scopes for fine-grained permissions within your application. Scopes are included in access tokens when the user authenticates in the context of this organization.

Updates a member's role, scopes, or status within an organization.

Common operations:

• Change role - Promote or demote a member (e.g., member → admin)
• Update scopes - Add or remove fine-grained permissions
• Suspend member - Temporarily block access without removing membership

Status changes:

• Setting status to suspended immediately blocks the member from accessing organization resources
• Setting status back to active restores access
• To permanently remove, use the Remove Organization Member endpoint instead

Removes a member from an organization.

This permanently removes the membership. The member:

• Immediately loses access to organization resources
• Will no longer see the organization in their memberships
• Retains their account in the issuer (if a user)

Alternative: To temporarily block access while retaining membership history, use Update Organization Member to set status to suspended instead.

Note: Removing the last owner of an organization may leave it without administrative access. Consider transferring ownership first.

Lists all groups defined in an organization.

Groups are named bundles of scopes that can be assigned to members. When a member is assigned a group, they inherit all of the group's scopes.

Creates a new group in an organization.

A group is a named bundle of scopes. Assign groups to members instead of managing individual scopes. When a group's scopes change, all members with that group automatically inherit the updated scopes.

Organizations can have up to 100 groups.

Retrieves a single group by ID.

Updates a group's name, description, or scopes.

When a group's scopes are updated, all memberships referencing this group will have their effective scopes re-computed and synced. This means scope changes propagate automatically to all members of the group.

Deletes a group from the organization.

Memberships that reference this group will have their effective scopes re-computed without the deleted group's scopes. The group ID remains in membership records but is silently ignored during scope resolution.

Rotates the OIDC client secret used for SSO authentication.

A new secret is generated and stored on the organization's SSO configuration. The new secret is returned in the response—store it securely, as it cannot be retrieved again.

Prerequisites:

• SSO must be enabled and configured with OIDC on the organization
• Update your identity provider with the new secret promptly

Note: Unlike client secret rotation, there is no grace period—the old secret is replaced immediately.

Adds a domain to the organization's SSO configuration for email-based IdP routing.

After adding a domain, you must verify ownership by creating a DNS TXT record with the provided values. Use the Verify SSO Domain endpoint to complete verification.

How it works:

1. Add the domain using this endpoint
2. Create the DNS TXT record as instructed in the response
3. Call the verify endpoint once the DNS record has propagated
4. Once verified, users with email addresses on this domain will be routed to the organization's SSO provider

Prerequisites:

• SSO must be enabled on the organization

Verifies ownership of an SSO domain by checking the DNS TXT record.

After adding a domain and creating the required DNS TXT record, call this endpoint to verify ownership. DNS propagation may take up to 48 hours, though it typically completes within minutes.

Response:

• verified: true — Domain ownership confirmed, SSO routing is active for this domain
• verified: false with error — Verification failed, check the error message for details

Removes a domain from the organization's SSO configuration.

Once removed, users with email addresses on this domain will no longer be routed to the organization's SSO provider. This action is immediate and permanent.

Note: You can remove both verified and unverified domains.

Lists invitations for an organization with optional status filtering.

Invitations allow you to invite users to join an organization before they have an account. When a user accepts an invitation, they become a member with the scopes defined in the invitation.

Invitation statuses:

• pending - Waiting for the invitee to accept or decline
• accepted - Invitee accepted and is now a member
• declined - Invitee explicitly declined the invitation
• expired - Invitation expired before being accepted
• revoked - Admin revoked the invitation

Use the status filter to find pending invitations that need follow-up or to audit historical invitations.

Creates a new invitation to join an organization.

An invitation email will be sent to the specified email address with a link to accept the invitation. The invitee does not need to have an existing account—they can create one when accepting.

Invitation lifecycle:

1. Admin creates invitation with email and scopes
2. System sends invitation email with secure link
3. Invitee clicks link and creates account (or logs in if existing)
4. Invitee accepts invitation and becomes organization member

Scopes:

Define what permissions the invitee will have in the organization. Common patterns:

• ["member"] - Basic read access
• ["member", "write"] - Read and write access
• ["admin"] - Full administrative access

Expiration:

By default, invitations expire after 7 days. You can customize this with expires_in_seconds (max 30 days).

Retrieves a specific invitation by ID.

Returns the full invitation details including:

• Invitee email - The email address the invitation was sent to
• Status - Current state of the invitation
• Scopes - Permissions the invitee will receive upon acceptance
• Timestamps - When created, expires, and accepted/declined/revoked

Note: The invitation challenge is never returned in API responses for security reasons.

Updates a pending invitation.

Only pending invitations can be updated. Once an invitation is accepted, declined, expired, or revoked, it cannot be modified.

Updatable fields:

• scopes - Change the permissions the invitee will receive
• user_title - Update the job title/role description
• message - Modify the custom invitation message
• expires_at - Extend or shorten the expiration (must be in the future)

Common operations:

• Extend expiration: Set expires_at to a future timestamp
• Change scopes before acceptance: Update scopes array
• Add context: Update message with additional information

Revokes a pending invitation.

Once revoked, the invitation link will no longer work and the invitee cannot accept it. This action is permanent.

Use cases:

• Cancel an invitation sent to the wrong email
• Remove access before it's granted
• Clean up invitations that are no longer needed

Note: Only pending invitations can be revoked. Invitations that have already been accepted, declined, or expired cannot be revoked.

Resends the invitation email to the invitee.

Use this when the original invitation email was not received or the invitee needs a reminder.

Requirements:

• Invitation must be in pending status
• Invitation must not be expired

Note: The invitation link and challenge remain the same—only the email is resent. Consider updating the expiration date if it's close to expiring.