Configure Access Control

Permissions control access to operations in Procivis One. 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.

note

This guide assumes you are deploying Procivis One with the Enterprise Backend. If you are integrating Core directly without the Enterprise Backend, you will need to manage permission mappings in your own token service. See STS Token Structure for token requirements.

Setup overview

After integrating with your IAM provider, complete access control setup in two steps:

1. Create system roles that group permissions by job function

2. Map your IAM roles to system roles per organization

The simplest way to complete these steps is via the Desk UI. Keep reading below for instructions using the APIs.

1. Create system roles

A system role is a named collection of permissions 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 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

Using the API

Use the Enterprise Backend admin endpoints at /api/sts/role/v1 to create, update, list, and retrieve system roles.

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"
    ]
}

2. Map IAM roles to system roles

Using the API

Use /api/sts/iam-role/v2 to create, update, list, and delete IAM role mappings.

warning

The name field must match the IAM role name exactly as it appears in your identity provider. A mismatch will cause the mapping to fail silently.

Example request:

{
  "name": "department-lead",
  "description": "Optional description",
  "roleOrganisations": {
    "bf5aae70-a426-409d-8c59-7a1a48163776": {
      "isGlobal": false,
      "organisations": [
        "320c5528-980c-41ae-9dc9-1d3f95396f4e"
      ]
    },
    "2db7d5d6-94a7-4942-a87a-33a3c0d1d168": {
      "isGlobal": true
    }
  }
}

The roleOrganisations object maps system role IDs to their organizational scope. For each system role, set isGlobal to true to apply it across all organizations, including any created in the future, or false and provide an organisations array to restrict it to specific organizations.

How permissions work

Permissions and enforcement

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.

• 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.

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.

Token structure

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

When Core receives an API request:

1. Core validates the token signature and claims

2. Core checks that the token contains the specific permission required for the operation (for example, CREDENTIAL_ISSUE for issuing credentials)

3. Core ensures all resources accessed belong to the token's organization

If any check fails, Core rejects the request with a 403 Forbidden response. To access a different organization, the user must obtain a new token scoped to that organization.

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

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 configuring system roles, include only the permissions relevant to the services and operations that role needs to access.

Retrieving available permissions

Call GET /api/config/v1 to retrieve the configuration and check the permissions object for all available permissions 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
  }
}