Permissions

Permissions control access to operations in Procivis One Core. When Core is configured in STS mode, permissions are enforced on all protected API endpoints, ensuring users can only perform actions they're authorized for within specific organizations.

Understanding permissions

What are permissions?

Permissions are granular, action-level controls that determine what operations a user can perform within an organization. Each permission corresponds to a specific API operation, such as issuing a credential or listing DIDs.

Key characteristics:

Action-level granularity: Each permission controls a specific operation (for example, CREDENTIAL_ISSUE, CREDENTIAL_LIST, DID_CREATE)
Organization-scoped: Permissions are checked per organization. The same user can have different permissions in different organizations.
Token-based: When Core is in STS mode, permissions are included in STS application tokens and validated on each request
Naming convention: Permissions follow a RESOURCE_ACTION pattern for easy identification

Enforcement:

Most Core API endpoints require specific permissions when Core is in STS mode. Some endpoints remain publicly accessible without authentication, such as system health checks and many SSI protocol endpoints that implement their own security mechanisms.

How permissions are enforced

Permissions are included in STS application tokens and validated by Core on each request.

Token structure:

Every STS application token is scoped to a single organization and includes a list of permissions. These permissions represent what the user is authorized to do within that organization.

Validation on each request:

When Core receives an API request:

Core validates the token signature and claims
Core checks that the token contains the specific permission required for the operation (for example, CREDENTIAL_ISSUE for issuing credentials)
Core ensures all resources accessed belong to the token's organization

If any check fails, Core rejects the request with a 403 Forbidden response.

Per-organization scope:

The same user may have different permissions in different organizations. To access a different organization, the user must obtain a new token scoped to that organization.

Permission management approaches

Using the Enterprise Backend

The Enterprise Backend provides a layer of abstraction between your IAM system and Core's granular permissions. How it works:

In you IAM system: Define broad-scoped roles that reflect actual job functions in your organization (for example, credential-manager, auditor, department-admin)
In the Enterprise Backend: Create system roles that group Core's granular permissions according to the principle of least privilege, then map your IAM roles to these permission collections

Key benefits:

Keep using IAM: Your identity provider continues to manage users and organizational roles without needing to understand Core's permission model
Apply least privilege: System roles let you define precise permission sets that align with specific job functions, ensuring users have only the access they need
Centralized management: Update permission mappings in one place as your needs evolve, without modifying your IAM configuration

Enterprise Backend admin endpoints:

/api/sts/role/v1 - Create and manage system roles (permission collections)
/api/sts/iam-role/v1 - Map IAM roles to system roles and organizations
/api/sts/organisation/v1 - Create and manage organizations with role assignments

Example scenario:

Your IAM has a role called credential-manager. You create a system role called "Credential Issuer" containing all CREDENTIAL_* and CREDENTIAL_SCHEMA_* permissions. You map the credential-manager IAM role to the "Credential Issuer" system role for Organization A.

When a user with the credential-manager IAM role requests access to Organization A, the STS issues a token containing all permissions from the "Credential Issuer" system role. The user can now issue credentials in Organization A.

info

For detailed information on creating system roles and IAM role mappings, see System roles
For a complete walkthrough with a realistic scenario, see the Access Control Tutorial

Direct integration (without Enterprise Backend)

If you're not using the Enterprise Backend, your token service must issue STS-compatible tokens that include Core permissions directly. This approach requires you to manage the IAM-to-permission mapping in your own systems.

Requirements:

Your token service must produce JWTs conforming to the STS Token Structure
Tokens must include the permissions array with Core permission strings
You must implement proper token signing with keys published at a JWKS endpoint
Core must be configured to validate tokens from your issuer

Workflow:

Retrieve available permissions: Call Core's configuration endpoint to get the current list of permissions (see Retrieving available permissions)
Define IAM-to-permission mappings: In your token service, map your IAM roles to Core permissions based on job functions
Issue tokens: When users authenticate, issue STS tokens containing the appropriate Core permissions for their roles and requested organization
Maintain mappings: Update your mappings when Core adds new permissions or your organizational needs change

Responsibilities:

When managing permissions directly, you are responsible for:

Keeping permission mappings current as Core evolves
Ensuring tokens include correct organization context (organisationId)
Implementing secure token signing and key rotation
Managing permission sets across all users and organizations
Documenting your IAM-to-permission mapping logic

Retrieving available permissions

Core publishes its permission set through the configuration endpoint. This is essential for understanding what permissions exist and for implementing IAM-to-permission mappings.

Configuration endpoint

Call GET /api/config/v1 to retrieve the current list of Core configurations.

The response includes a permissions object structured by resource type:

{
  "permissions": {
    "CACHE": [
      "CACHE_DELETE"
    ],
    "CREDENTIAL": [
      "CREDENTIAL_DELETE",
      "CREDENTIAL_DETAIL",
      "CREDENTIAL_EDIT",
      "CREDENTIAL_ISSUE",
      "CREDENTIAL_LIST",
      "CREDENTIAL_REACTIVATE",
      "CREDENTIAL_REVOKE",
      "CREDENTIAL_SHARE",
      "CREDENTIAL_SUSPEND",
      "HOLDER_CREDENTIAL_LIST"
    ],
    "CREDENTIAL_SCHEMA": [
      "CREDENTIAL_SCHEMA_CREATE",
      "CREDENTIAL_SCHEMA_DELETE",
      "CREDENTIAL_SCHEMA_DETAIL",
      "CREDENTIAL_SCHEMA_LIST",
      "CREDENTIAL_SCHEMA_SHARE"
    ],
    // ... additional resource types
  }
}

This endpoint returns the complete set of permissions available in Core, regardless of your deployment configuration or organizational setup. Permissions are grouped by resource type to help you understand related operations and build logical permission sets.

Permission naming and API mapping

Naming convention

Core permissions follow a consistent RESOURCE_ACTION pattern:

Resource: The entity type (for example, CREDENTIAL, DID, STS_ORGANISATION)
Action: The operation (for example CREATE, LIST, DELETE, REVOKE)

Examples:

CREDENTIAL_ISSUE: Issue a credential
DID_CREATE: Create a DID
STS_ORGANISATION_EDIT: Update organization details

This naming convention makes it straightfoward to identify what each permission controls and to map API operations to required permissions.

Service-specific permissions

Some permissions are only checked by specific services within the Procivis One platform. Other services ignore these permissions.

Permission Pattern	Service	Purpose
`OPENID_PROVIDER_*`	Bridge	Manage OIDC provider configurations
`STS_ROLE_*`	Enterprise Backend	Manage system roles
`STS_IAM_ROLE_*`	Enterprise Backend	Configure IAM role mappings
`STS_ORGANISATION_*`	Core	Admin-level organization management

When constructing tokens for technical users or configuring system roles, include only the permissions relevant to the services and operations that user needs to access.

System roles (Enterprise Backend)

System roles are named collections of Core permissions created and managed through the Enterprise Backend. They simplify permission management by grouping related permissions into reusable sets.

What are system roles?

A system role is a named permission set that you define based on job functions or operational needs. Instead of assigning individual permissions to users, you create system roles that represent common access patterns and map your IAM roles to these system roles.

Example system roles:

Credential Issuer: Includes all CREDENTIAL_* and CREDENTIAL_SCHEMA_* permissions for creating schemas and issuing credentials
Verifier: Includes PROOF_* permissions plus CREDENTIAL_DETAIL for requesting and verifying presentations
Read-Only Auditor: Includes all *_LIST and *_DETAIL permissions for viewing resources without modification capabilities
Organization Administrator: Includes ORGANISATION_* permissions for managing organizational settings

Creating and managing system roles

Use the Enterprise Backend admin endpoints at /api/sts/role/v1 to:

Create new system roles with selected permissions
Update existing role permission sets
List all available system roles
Retrieve details for specific roles

When creating a system role, you select which Core permissions to include from the full permission catalog. See Retrieving available permissions to obtain the complete list of available permissions.

Example request:

{
    "name": "Credential Issuer",
    "permissions": [
        "CREDENTIAL_DELETE",
        "CREDENTIAL_DETAIL",
        "CREDENTIAL_EDIT",
        "CREDENTIAL_ISSUE",
        "CREDENTIAL_LIST",
        "CREDENTIAL_REACTIVATE",
        "CREDENTIAL_REVOKE",
        "CREDENTIAL_SHARE",
        "CREDENTIAL_SUSPEND",
        "CREDENTIAL_SCHEMA_CREATE",
        "CREDENTIAL_SCHEMA_DELETE",
        "CREDENTIAL_SCHEMA_DETAIL",
        "CREDENTIAL_SCHEMA_LIST",
        "CREDENTIAL_SCHEMA_SHARE"
    ]
}

Using system roles with IAM role mappings

System roles connect to your IAM infrastructure through IAM role mappings. You define which of your IAM roles should grant which system roles in which organizations.

Mapping structure:

IAM role → System role(s) + Organization(s)

This means:

One IAM role can map to different system roles in different organizations
One IAM role can grant access to multiple organizations with different permission sets per organization
One IAM role can map to multiple system roles within the same organization (permissions are combined)

Example mapping:

Your IAM has a role called department-lead. You create two mappings:

department-lead → "Credential Issuer" system role in Organization A
department-lead → "Verifier" system role in Organization B

When a user with the department-lead IAM role requests access to Organization A, they receive all permissions from the "Credential Issuer" system role. When the same user requests access to Organization B, they receive all permissions from the "Verifier" system role.

Managing IAM role mappings

Use the Enterprise Backend admin endpoints at /api/sts/iam-role/v1 to:

Create mappings between IAM roles and system roles for specific organizations
Update existing mappings
List all IAM role mappings
Delete mappings when no longer needed

IAM role mapping structure:

{
  "name": "department-lead",  // IAM role name from your identity provider
  "organisationRoles": {
    // Organization ID: array of system role IDs
    "320c5528-980c-41ae-9dc9-1d3f95396f4e": [
      "bf5aae70-a426-409d-8c59-7a1a48163776"  // System role ID
    ],
    "60a3a5d2-8d94-492c-a997-cbbce31aa7ef": [
      "2db7d5d6-94a7-4942-a87a-33a3c0d1d168"
    ]
  }
}

The organisationRoles object maps organization IDs to arrays of system role IDs. Multiple role IDs in an array means the user receives combined permissions from all listed roles. Multiple organizations in the mapping means the IAM role grants access to all listed organizations with their respective system roles.

In this example, users with the department-lead IAM role receive:

One system role in the first organization
A different system role in the second organization

Understanding permissions​

What are permissions?​

How permissions are enforced​

Permission management approaches​

Using the Enterprise Backend​

Direct integration (without Enterprise Backend)​

Retrieving available permissions​

Configuration endpoint​

Permission naming and API mapping​

Naming convention​

Service-specific permissions​

System roles (Enterprise Backend)​

What are system roles?​

Creating and managing system roles​

Using system roles with IAM role mappings​

Managing IAM role mappings​