Skip to main content
This guide covers the API calls a tenant user makes to work across the organizations of a tenant. To do the same from the dashboard, see Work across organizations.

​
Before you start

  • Tenant user login. Call these endpoints with a tenant user’s login token. Each endpoint’s API reference page lists the callers it accepts.
  • Signed changes. Every call that changes something, such as creating an organization or inviting a tenant user, needs a user action signature. See Sign requests.
  • Token scope. A token is scoped either to the tenant or to one organization. Tenant endpoints (/tenant/*) need a tenant-scoped token. Every other endpoint needs a token scoped to the organization you act in.

​
Sign in to the tenant

Log in with Create Login Challenge and Complete User Login, as in the regular login flow. Pass tenantId instead of orgId in the login challenge. The token you receive is scoped to the tenant.

​
Create an organization

Call Create Org with a tenant-scoped token. It needs the Tenant:Orgs:Create tenant permission.
  • name: the organization’s name.
  • keyStores: the key stores the organization uses, picked from those assigned to your tenant. Pass at least one, and mark exactly one with primary: true. New keys use the primary key store by default. See Organizations and key stores. Contact our Support Team for the IDs of your tenant’s key stores.
You become the first org admin of the new organization.

​
Add a tenant user

Call Create Tenant User with a tenant-scoped token. It needs the Tenant:Users:Create tenant permission. DFNS emails the new tenant user a registration code. They start with no tenant permissions and no access to any organization.

​
Give a tenant user access to an organization

Access takes two separate calls, both made with a token scoped to the target organization:
1

Invite the tenant user

Call Invite Tenant User with the tenant user’s email and kind: "TenantUser". It needs the Auth:Users:Create permission in the organization, held for example by an org admin. The tenant user joins with no org permissions.
2

Assign org permissions

Call Assign Permission with the tenant user’s ID as identityId. It needs the Permissions:Assign permission in the organization, held for example by an org admin. Assign ManagedFullAdminAccess for full access, or a read-only role for monitoring. See Roles and permissions.

​
Act in an organization

Acting in an organization takes two separate calls:
1

Exchange the token

Call Exchange Access Token with the organization’s ID as target. You can start from a tenant-scoped token or from a token scoped to another organization, and you must have access to the target organization. To go back to the tenant, pass the tenant ID as target.This call needs no user action signature. The new token expires at the same time as the current one, and on its own it can only read.
2

Call the organization's endpoints

Use the new token for the organization’s endpoints. Every change, such as a transfer, is a separate call that needs a user action signature with your credentials, as in any organization.

​
Remove a tenant user

  • From one organization: call Delete User with a token scoped to that organization. It needs the Auth:Users:Delete permission in the organization. The tenant user loses their org permissions and access there, and keeps their other organizations.
  • From every organization: call Delete Tenant User with a tenant-scoped token. It needs the Tenant:Users:Delete tenant permission.
Either call is refused if it would leave the tenant or an organization without an admin, or a policy without enough approvers.

​
Change the status of an organization

Call Update Org Status with a tenant-scoped token and status set to Active, Suspended, or Archived. It needs the Tenant:Orgs:Status:Update tenant permission. Restoring an archived organization is refused if your tenant has reached its organization limit. See Organization status.

​
Onboard client org users with delegated registration

To onboard the org users of a client organization from your own application, without registration emails from DFNS, use delegated registration:
  1. Create each org user with registration: "Delegated".
  2. Register them through a service account in that client organization.
Delegated registration for org users is enabled on demand, for the whole tenant. Org users registered this way sign in through the regular login flow: delegated login is for end users only.
Last modified on November 10, 2026