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
  • 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 is straightforward: a digital wallet receives issuances and makes presentations as a single organization

Core API vs. Desk API​

Organization operations

Core API & Desk API

The Core API uses a single token for most requests and includes no user or session management. For relevant endpoints, you specify which organization performs each action directly in API parameters.

The Desk API is our enterprise solution with OIDC authentication, user roles, and session-based organization switching. You can assign roles at multiple layers allowing for complex multi-tenancy. Admins get enhanced management tools like adding logos and descriptions to organizations, and deactivating organizations. See the Desk API organization section for more.

Organizations in the Core API​

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.

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.

Organizations in the Desk API​

Current organization​

While a user is logged in to the Desk API, the current 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 current organization at a time and the user can only take permissioned actions of the current organization.

Related guide: Authentication and authorization

Creating and managing organizations​

Admin users assign functional roles to each organization — some subset of issuer, holder, or verifier — setting the outer boundary of what any user is allowed to do within an organization. Logos and organization descriptions can also be set for improved user experience in multi-tenant organizations.

Admin users can also deactivate organizations, instantly revoking access for all users within that tenant without affecting other organizations.

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.

Admin users manage complex organizations by assigning roles at three distinct layers — organizational, custom, and IAM—which combine to create granular permissions for individual users.

Related guide: Organizations tutorial

Holding​

Digital wallets typically use a single organization. Since keys, identifiers, and credentials belong to a specific organization, each organization functions as a separate digital wallet with its own set of credentials.

For most use cases, creating one organization and using it for all wallet operations provides the simplest and most flexible approach. While it's possible to implement applications that work across multiple organizations, this may be useful primarily for specialized scenarios where credential separation is specifically required.

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.

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.