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 granular permission-based authorization
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
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
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.
STS
The Desk API uses the Security Token Service (STS) to create and manage
organizations via the /api/sts/organisation/v1 endpoint. These endpoints
are only accessible to users with the admin role, assigned in the Desk
configuration at sts.iam.adminRole.