Skip to main content

Organizations

Every credential issuance, verification, or holder operation must be performed within an organization. Whether you're issuing credentials, verifying presentations, or building a wallet application, creating and configuring organizations is the essential first step in using the platform.

Understanding organizations​

What is an organization?​

An organization is the central isolation and tenancy unit within Procivis One. All credential-related operations – issuing, holding, and verifying – must occur within an organizational context.

Key characteristics:

  • Entity container: Organizations contain all entities including DIDs, keys, credential schemas, credentials, and proofs
  • Required for operations: You must create at least one organization before performing credential operations
  • No hierarchy: All organizations exist at the same level. There are no parent organizations or sub-tenants.
  • Isolation: Organizations cannot share or reference identifiers, credentials, or proofs across organizational boundaries

Organizational equality​

Procivis One treats all organizations as independent and equal. Different capabilities and access levels are managed through granular user permissions, and organizational roles (in the Enterprise Backend), not through hierarchical relationships.

Organizations and multi-tenancy​

Organizations provide strict multi-tenancy through isolation of data and enforcement of access controls. How this isolation is enforced depends on the authentication mode configured for your services.

Multi-tenancy is enforced by Core on every API request. Each STS token contains a single organization context (organisationId). When Core receives a request, it:

  • Validates the STS token signature and claims
  • Checks that the user has the required permissions within the token's organization
  • Ensures all requested resources belong to the token's organization
  • Logs the request subject for audit purposes

This means users cannot access or modify resources outside their current organizational context, even if they have access to multiple organizations. To work with a different organization, users must obtain a new token scoped to that organization.

The Enterprise Backend always operates in STS mode and passes STS tokens to Core with each request. Core performs the actual tenant isolation and permission enforcement.

When Core is in non-STS modes (STATIC or INSECURE_NONE)​

Multi-tenancy is not enforced. All organizations are accessible through the Core API. You must specify which organization you're working with using the optional organization query parameter on relevant endpoints.

Example using static token mode:

curl -X 'GET' \
  'https://example.com/api/key/v1?page=0&pageSize=30&organisationId=6a9275e4-8a28-4170-b79c-ee48c749f4a9' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer token'

Without tenant enforcement, it's the API client's responsibility to manage organizational context and prevent unauthorized cross-organization access.

Software data isolation​

Regardless of Core's authentication mode, the underlying data model maintains isolation between organizations:

  • Credentials in one organization cannot be accessed in another organization
  • Identifiers such as DIDs and keys cannot be shared across organizations
  • Proof requests and presentations are scoped to a single organization
  • All entities remain organizationally isolated in the database

Hardware data isolation​

Strict physical isolation can be achieved by running multiple Core instances on different hardware.

Structuring your organizations​

Most deployments use multiple organizations to separate different business contexts or operational boundaries. Some deployments may use a single organization.

Multi-Organization deployments​

Organizations provide logical separation of entities – DIDs, keys, credentials, and other resources. This separation serves two main purposes:

  • Operational isolation: Different business units, credential programs, or use cases maintain independent key material and credential stores. Changes in one organization don't affect others.
  • Access control: Following the principle of least privilege, users and technical users only receive access to the organizations they need. If a department doesn't need access to another department's credentials or keys, they shouldn't have access. You can always grant specific users access across multiple organizations when needed.

Organizations act as security and administrative boundaries within your deployment.

Example 1: Government​

A national government operates multiple departments with distinct credential functions.

Organization structure​

  • PID Issuance Org: Issues national person identification credentials (PIDs). Maintains high-security key material and strict issuance policies.

  • National Wallet Provider Org: Provides wallet unit attestations to the national ID ecosystem. Acts as trust anchor for mobile wallets.

  • Department A Verification Org: Verifies PIDs and professional credentials for business licensing.

  • Department B Verification Org: Verifies PIDs and employment credentials for social services.

Why separate organizations:​

  • PID issuance operations isolated from verification departments

  • Each verifier maintains independent DIDs and verification policies

  • Compromised keys in one department don't affect others

Example 2: University​

A university separates academic and employment credential programs.

Organization structure​

  • Academic Credentials Org: Issues diplomas, transcripts, course completion certificates

  • Employee Credentials Org: Issues employee badges, parking permits, building access credentials

Why separate organizations​

  • Different data governance requirements (student records vs. HR records)

  • Different administrative teams manage each credential program

  • Separate key management and security policies

Example 3: Enterprise Business Wallets​

A large corporation implements business wallets for different departments, where each department manages credentials related to their operations.

Organization structure​

Each department receives its own holder organization: HR, Finance, Legal, Procurement, etc. Each organization maintains its own wallet with department-specific credentials.

Why separate organizations​

Access control follows organizational structure (Finance staff can't access Procurement's wallet).

Single-organization deployments​

Some scenarios work well with a single-organization:

  • Small businesses: Straightforward credential operations without need for internal separation
  • Focused use cases: Single-purpose deployments (for example, a company that only verifies employee credentials)
  • Pilot programs: Testing credential issuance or verification before scaling to production
mobile wallets

Individual mobile wallet applications typically use single-organization architecture, with one organization per user or device. This document focuses on server-based, multi-tenant architectures. For mobile wallet implementation guidance, see Wallet workflow.

Organization roles (Enterprise Backend)​

The Enterprise Backend adds organization roles — a permission boundary mechanism that restricts what operations can be performed within an organization. Organization roles are only available when using the Enterprise Backend; the Core API does not implement organization roles.

Available roles​

  • Issuer: Create and manage credential schemas, issue credentials
  • Holder: Store credentials, create presentations, respond to proof requests
  • Verifier: Request and verify presentations
  • Wallet provider: Issue wallet unit attestations

How roles work​

Organization roles are enforced by the Secure Token Service (STS) during token issuance. When the STS creates an application token, it intersects the user's IAM permissions with the organization's role permissions.

Example​

If an admin creates an organization with the following roles:

  • Issuer
  • Wallet provider

Then no user will ever be issued an application token with permissions to hold credentials or verify proof requests in that organization, regardless of what roles they have in the organization.

Creating and managing organizations​

Initial setup​

For information on configuring the initial admin user during deployment, see Setting up the first admin. Once set up (admins are given appropriate access), you should remove the configured super admin and use the endpoints described below to continue.

Core API​

Endpoints: /api/organisation/v1

Available operations:

  • List organizations: Retrieve all organizations accessible to you
  • Retrieve organization: Get details for a specific organization
  • Create organization: Create a new organization
    • Send an empty POST request – a UUID will be generated
    • Optionally provide a UUID and/or organization name
  • Update organization: Update or insert an organization
    • Change or add an organization name
    • Deactivate the organization
    • Configure wallet provider parameters for issuing wallet unit attestations

Authentication modes:

  • STS mode: Organization context included in your token. Core checks your permissions for each operation.
  • Static/None mode: All organizations are accessible. Specify the target organization using optional organisation query parameter on relevant endpoints.

Enterprise Backend (Desk API)​

The Enterprise Backend provides two sets of organization endpoints: organization context management and administrative options.

  1. Organization context (api/organisation/v1)

  • List your organizations: View all organizations you have access to
  • Switch active organizations: Change your active organization context and receive a new token scoped to that organization

  1. Organization administration (/api/sts/organisation/v1)

Requires admin permissions. Allows you to:

  • List all organizations: Retrieve all organizations in the system
  • Retrieve organization: Get details for a specific organization
  • Create organization: Create a new organization with:
    • Name (required)
    • Role assignment (required)
    • Logo
    • Description
    • Slug - improves link sharing to org-specific resources
  • Update organization: Modify:
    • Name
    • Role assignment
    • Logo
    • Description
    • Slug
    • Deactivation status
    • Wallet provider parameters
  • Delete organization: Remove an organization from the system

Organization lifecycle​

Creation​

When you create an organization:

  • Assign an organization name (optional in Core API, required in Enterprise Backend)
  • Enterprise Backend: Assign organization role(s), optionally add description, logo, and slug
  • System generates a UUID (or you can provide one in Core API)
  • Organization is immediately active and ready for use

Once created, you can begin adding entities such as keys, DIDs, credential schemas, and credentials to the organization.

Active operations​

During normal operation, most API activities are scoped to organizations:

  • Credential issuance, verification, and storage operations reference the organizational context
  • Users can have different permission sets for different organizations
  • In STS mode, each app token is scoped to a single organization
  • All entities (keys, DIDs, credentials, proofs) remain isolated within their organization

Exceptions:

  • System configuration
  • Build info
  • Health check
  • System metrics

Deactivation​

Organizations can be deactivated to prevent further use while preserving data:

  • All organization data is retained in the system
  • Entities within the organization (keys, DIDs, credentials, schemas) remain visible through API queries
  • New operations using the organization's entities are prevented
  • Existing credentials remain valid for holders and verifiers, at least at the time of organization deactivation
    • Deactivation affects the issuer's ability to issue new credentials, not previously issued ones
    • Note that credentials issued with short validity windows and relying on frequent reissuance (for example ISO mdocs) will be rendered invalid more quickly as reissuance is disabled once an organization is deactivated

Deactivation is useful for temporarily or permanently disabling an organization without data loss, such as when shutting down a department or ending a credential program.

Deletion (Enterprise Backend only)​

The Enterprise Backend supports deletion of organizations through the admin endpoints. When an organization is deleted, the organization and all its entities are removed from the system.