Skip to main content

Organizations

Learn how to work with organizations and manage multi-tenancy.

The Organization is the fundamental unit of Procivis One. All actions related to issuing, holding and verifying are taken by an organization. This means that keys, DIDs, credentials and proofs belong to the organization used to create them and to no other.

Key takeaways:

  • Whatever your use case, an organization must be created first
  • Holding is straightforward: a digital wallet receives issuances and makes presentations as a single organization
  • Issuers and verifiers can create multiple organizations to keep different sets of identifiers and other entities separated
  • The Desk API offers multi-tenancy and accepts user management integration from Keycloak

Holding​

Digital wallets require only one organization. Since all keys, identifiers and credentials belong to only one organization, a second organization could only have a different set of keys, identifiers and credentials and so would effectively be a different digital wallet. Though a digital wallet application can be implemented to use multiple wallet instances, a model of holding personal credentials and identities within distinct silos may suffer from a lack of cross-situational flexibility or be useful for a more limited set of use cases.

Creating a wallet organization​

As soon as a wallet has created an organization, it can create a key and an associated identifier and then begin accepting credentials from issuers and making presentations to verifiers. See the wallet workflow for an example of initializing a wallet with the SDK.

Using a wallet organization​

Most methods used by a digital wallet either require the explicit specification of the organization taking the action or involve passing the ID of an entity which is owned by an organization.

Core API​

Organization operations

Core API

Creation​

There are two options for creating an organization:

  • Use the POST endpoint. You can optionally pass a UUID and/or a name. If you pass no UUID, one will be created. If you pass a UUID that already exists in the system, the system returns an error. If you pass no name, the UUID will be used.
  • Use the PUT endpoint. Here you must pass a UUID as a path parameter and a name in the request body. If the UUID already exists in the system, the name is updated. Otherwise, a new organization is created.

Usage​

The Core API uses a static token in the header of all calls, exposing all organizations and resources equally. For most calls to the Core API, the organization to take the action with must be specified.

Desk API​

Organization operations

Desk API

In contrast to the Core API, the Desk API stores the active organization in the user session. Calls made to the Desk API are made within the context of the active organization.

See the authentication and authorization docs for details on login and session management.

Active organization​

While a user is logged in to the Desk API, the active organization is stored in the user session. The user can switch to other organizations to which they belong at any time, though there can only be one active organization at a time and the user can only take permissioned actions of the active organization.

Multi-tenancy​

The Desk API offers multi-tenancy through its use of organizations and user permissions. This enables issuers and verifiers to separate different departments, functions and roles. The system supports the creation of as many organizations and users as is needed.

A user of the Desk API is part of one or more organizations and is permissioned to take a set of actions within each organization.

Multi-tenancy is managed by creating organizations where distinct sets of identifiers, credentials, or proofs are desired. Cross-organizational collaboration is managed by users having different sets of permissions within different organizations.

See how to set up the Desk API for guidance on setting up multi-tenancy.

Permissions​

For the Desk API, permissions to take actions in the API are managed on the level of the user account within the organization. Each user account belongs to one or more organizations and is allowed some subset of API actions within each organization.

The core functionalities to issue, hold, and verify credentials are listed in the permissions field when listing organizations and logging in. Each entry in permissions relates to a single method of an API endpoint and follows a general format: [RESOURCE]_[ACTION]. For example, CREDENTIAL_LIST is permission to list credentials in the organization and DID_DEACTIVATE is permission to deactivate a DID.

Exception

When a user authenticates to the Desk API with a credential, they can view their own login credential details, even if the credential belongs to a different organization.

To use this exception:

  • The request must be a GET to /api/credential/v1/{credentialId}.
  • The credentialId must match the credential used to log in to the current session.

Admin role​

In order to manage multi-tenancy, an Admin role should be assigned. Admin users can see all organizations and can switch their active organization to any non-Admin organization. Admin users can also manage trust anchors and trust entities.

Assign the admin role​

The Admin role is assigned at the Group level. To assign the Admin role, add the following attribute to the designated Group:

  • is_admin: true

Then create at least one Admin user by assigning the editor and reader roles in that Group. For example, if the Group is ADMIN, at least one user in the group must have the following roles:

  • ADMIN_READER
  • ADMIN_EDITOR

From within the API, the Admin status is returned from the GET /api/profile/v1 endpoint as a boolean in the isAdmin field.