> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dfns.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage organizations and tenant users

> Create organizations, give tenant users access to them, act in them, and change their status with the DFNS API.

This guide covers the API calls a tenant user makes to work across the organizations of a [tenant](https://docs.dfns.co/core-concepts/tenants.md). To do the same from the dashboard, see [Work across organizations](https://docs.dfns.co/guides/work-across-organizations.md).

## 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](https://docs.dfns.co/guides/developers/signing-requests.md).
* **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](https://docs.dfns.co/api-reference/auth/create-login-challenge.md) and [Complete User Login](https://docs.dfns.co/api-reference/auth/complete-user-login.md), as in the [regular login flow](https://docs.dfns.co/api-reference/auth/login-flows.md#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](https://docs.dfns.co/api-reference/tenant/create-org.md) 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](https://docs.dfns.co/advanced/deployment-models#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](https://docs.dfns.co/api-reference/tenant/create-tenant-user.md) 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](https://docs.dfns.co/api-reference/auth/invite-tenant-user.md) 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](https://docs.dfns.co/api-reference/permissions/assign-permission.md) 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](https://docs.dfns.co/core-concepts/roles-and-permissions.md).

## Act in an organization

Acting in an organization takes two separate calls:

**1. Exchange the token**

Call [Exchange Access Token](https://docs.dfns.co/api-reference/auth/exchange-access-token.md) 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](https://docs.dfns.co/api-reference/auth/delete-user.md) 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](https://docs.dfns.co/api-reference/tenant/delete-tenant-user.md) 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](https://docs.dfns.co/api-reference/tenant/update-org-status.md) 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](https://docs.dfns.co/core-concepts/organizations.md#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](https://docs.dfns.co/api-reference/auth/registration-flows.md#delegated-registration-flow):

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](https://docs.dfns.co/api-reference/auth/login-flows.md#regular-login-flow): delegated login is for end users only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.