Understanding Organizations

You created your first organization during quickstart. This guide explains what organizations are, how they enforce isolation, and how to plan your organization structure as your deployment grows.

Isolation and multi-tenancy

An organization is the central tenancy unit in Procivis One. All creation and interaction activities are scoped to an organization — keys, credentials, certificates, proofs, and similar entities belong to a single organization and cannot be accessed from another. Credential schemas and proof schemas can be shared across organizations as a convenience for deployments that use consistent data structures.

Enforcement in STS mode

In production deployments using the Enterprise Backend, multi-tenancy is enforced by Core on every API request. Each STS token contains a single organization context. When Core receives a request, it:

1. Validates the token signature and claims

2. Checks that the user has the required permissions within the token's organization

3. Ensures all requested resources belong to that organization

4. Logs the request subject for audit purposes

Users cannot access or modify resources outside their current organizational context. To work with a different organization, a user must obtain a new token scoped to that organization.

Data isolation

Regardless of authentication mode, the underlying data model maintains strict isolation between organizations. Credentials, identifiers, proof requests, and presentations are all scoped to a single organization and cannot be accessed from another. Strict physical isolation can be achieved by running multiple Core instances on separate hardware.

Organization roles

The Enterprise Backend adds organization roles — a permission ceiling that restricts what operations can be performed within an organization.

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 and curate trust lists for wallets
• National Registry: Operate a registry of wallet-relying parties
• Access Certificate Provider: Issue Access Certificates to registered wallet-relying parties
• Registration Certificate Provider: Issue Registration Certificates to registered wallet-relying parties

How roles work

Organization roles are enforced by the STS during token issuance. When the STS creates an application token, it intersects the user's system role permissions with the organization's role permissions. If an organization is assigned only the "Issuer" role, no user will ever receive an application token with permissions to hold credentials or verify proof requests in that organization, regardless of their system role assignments.

This means organization roles set the outer boundary of what is possible within an organization. User permissions can only be as broad as the organization's roles allow.

Organization lifecycle

Creation

When you create an organization you assign a name and one or more organization roles. A UUID is generated automatically. Once created, the organization is immediately active and you can begin adding keys, certificates, credential schemas, and credentials to it.

For API reference, see Create organization.

Deactivation

Organizations can be deactivated to prevent further use while preserving all data. After deactivation:

• All organization data and entities remain visible through API queries
• New operations using the organization's entities are prevented
• Previously issued credentials remain valid for wallets and verifiers

One important exception: credentials with short validity windows that rely on frequent reissuance, such as ISO mdocs, will become invalid more quickly after deactivation, since reissuance is disabled.

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

The Enterprise Backend supports deletion of organizations through the admin endpoints at /api/sts/organisation/v1. When an organization is deleted, the organization and all its entities are permanently removed from the system.

Plan your organizations

Most deployments use multiple organizations to separate different business contexts or operational boundaries. Organizations provide two main benefits when used this way:

• Operational isolation: Different business units or credential programs maintain independent key material and credential stores. Changes in one organization don't affect others.
• Access control: Users and technical users only receive access to the organizations they need, following the principle of least privilege.

Examples

Government

A national government operates multiple departments with distinct credential functions:

• PID Issuance Org — Issues national person identification credentials with high-security key material and strict issuance policies
• National Wallet Provider Org — Issues wallet unit attestations and 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

Separating these organizations means PID issuance operations are isolated from verification departments, each verifier maintains independent DIDs and verification policies, and a compromised key in one department does not affect others.

University

A university separates academic and employment credential programs:

• Academic Credentials Org — Issues diplomas, transcripts, and course completion certificates
• Employee Credentials Org — Issues employee badges, parking permits, and building access credentials

These programs have different data governance requirements, different administrative teams, and different security policies, all good reasons for organizational separation.

Enterprise

A large corporation implements holder organizations per department — HR, Finance, Legal, Procurement — each maintaining its own wallet with department-specific credentials. Access control follows the organizational structure, so Finance staff cannot access Procurement's wallet.

Single-organization deployments

Some scenarios work well with a single organization: small businesses with straightforward credential operations, single-purpose deployments, or pilot programs before scaling to production.

note

Individual mobile wallet applications typically use single-organization architecture with one organization per user or device. For mobile wallet implementation guidance, see Wallet workflow.