Platform Management API

Added in version 2.6.0

The Platform Management service enables provisioning of user accounts and resources before users access the system via the Admin API. Access to the Admin API is only permitted through a Service Account. The API provides secure, phased provisioning of WebIDs and Storage containers with proper access control throughout the process.

Critical Security Requirements

Username Binding Security

The Platform Management service hosts an Admin API that can be integrated with a backend user provisioning system to set up users on ESS. The binding between ESS and users in the Identity Provider (IdP) is the username.

It is vital that accounts with the same username are created in the IdP BEFORE calling the Admin API. Failing to do this could allow a malicious user to claim the same username assigned for someone else, leading to unauthorized access to resources intended for another user.

Always ensure proper coordination between IdP account creation and ESS provisioning operations.

Provisioning Workflow Scenarios

Depending on your organization's processes, the Platform Management API supports several provisioning workflows:

Existing IdP Users: Users already have accounts in the IdP, and the organization provisions ESS resources for these existing users
User Self-Registration: A user creates an account in the IdP first, then the organization provisions ESS resources for that user
Organization-Managed: The organization creates both the IdP account and ESS resources for new users in a coordinated process

In all scenarios, the IdP account with the target username must exist before calling the Admin API provisioning endpoints.

Service Accounts

The Platform Management service APIs are accessible only through Service Accounts. A Service Account is a specialized account type with restricted privileges:

Provisioning Access: Can call /admin/provision endpoints to create user accounts
No Personal Storage: Service Accounts do not have their own storage containers
Read-Only WebID: Service Account WebID documents are read-only and cannot be modified
Limited Scope: Cannot issue Access Credentials on behalf of themselves
Temporary Elevated Access: During setup phase, granted privileges to work on users' behalf
Automatic Revocation: All elevated privileges are removed when accounts are activated

Initial Service Account

Following installation of ESS the Platform Management service will automatically create a single Service Account at startup, using the name specified in the INRUPT_PLATFORM_ACCOUNT_PROVISION_SERVICE_USERNAME environment variable, if this account does not exist. Once created, the username cannot be changed and the Service Account cannot be removed.

On startup, the Platform Management service will automatically create a single Service Account using the specified username, if this account does not exist. Once created, the username cannot be changed and the Service Account cannot be removed.

If the INRUPT_PLATFORM_ACCOUNT_PROVISION_SERVICE_USERNAME environment variable is not set, the service will fail to start.

The initial Service Account is granted specific permissions to provision endpoints and serves as the foundation for all platform provisioning operations.

Service Account Configuration

The initial Service Account is configured via environment variables:

INRUPT_PLATFORM_ACCOUNT_PROVISION_SERVICE_USERNAME=provision-service

Critical Security Requirement

The Service Account credentials have administrative privileges to modify ESS user accounts and resources. Access to this account must be strictly governed.

Ensure proper security controls are in place for the Service Account in your IdP configuration.

Provisioning Overview

The Platform Management service implements a two-phase provisioning lifecycle:

Setup Phase: Service Account creates and configures user resources
Active Phase: Resources are transferred to user ownership and Service Account privileges are revoked

Service Account Privileges During Setup

When a provisioning session is in setup state, the Service Account is granted temporary elevated privileges to work on the user's behalf:

Storage Operations: Create containers, upload files, ingest data into Storage created for the user, and manage resources
Access Credential Issuance: Issue Access Grants on behalf of the user for third parties to access user resources
WebID Management: Read and update WebID documents on user's behalf

Privilege Revocation on Activation

When PUT /admin/provision/{id}/activate is called:

Immediate Revocation: Service Account loses all elevated privileges instantly
User Ownership: Resources are transferred to end user control
Access Lockout: Service Account can no longer access activated user resources
Atomic Transition: No gap between privilege revocation and user ownership

This ensures proper security boundaries between administrative provisioning and user ownership.

Platform Management Endpoints

By default, the Platform Management service runs from the following root URL:

https://platform.<ESS Domain>

The Platform Management service Admin API consists of the following endpoints:

Endpoint

Description

POST /admin/provision

Create a new user provisioning session with WebID

GET /admin/provision/{id}

Get status of a provisioning session

PUT /admin/provision/{id}/storage

Add storage container to a provisioning session

PUT /admin/provision/{id}/activate

Activate session and transfer ownership to user

DELETE /admin/provision/{id}

Deprovision resources (setup state only)

Create Provisioning Session

Create a new user account with WebID in setup state.

Input

Endpoint

https://platform.{ESS Domain}/admin/provision

Method

POST

Authorization

An access token for a Service Account that has write access to the provision endpoints.

Content-Type

application/json

Payload

A JSON object containing user data and optional proof for compliance purposes.

The provisioning request payload is represented as JSON:

{
  "userData": {
    "username": "<username>"
  },
  "proof": "<compliance proof data>"
}

Request Validation Rules

The userData field must be present
The userData.username field must be present and non-empty
The proof field is optional but recommended for compliance workflows. This field can contain any compliance-related evidence (consent forms, legal documents, etc.) and is stored opaquely by the service for audit purposes.

Security Prerequisite

Before calling this endpoint, ensure that an account with the specified username already exists in your Identity Provider (IdP). The username serves as the binding between ESS and the IdP user account. Provisioning without a corresponding IdP account creates a security vulnerability where malicious users could claim the username.

Example Request

POST /admin/provision HTTP/1.1
Host: platform.example.com
Authorization: DPoP <dpop-bound-jwt>
DPoP: <proof-of-possession-token>
Content-Type: application/json

{
  "userData": {
    "username": "johndoe"
  },
  "proof": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Output

Creates a new user account in setup state. The response includes the provisioning session ID, WebID, and initial (empty) storage array.

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c",
  "state": "setup",
  "webid": [
    "https://id.example.com/johndoe"
  ],
  "storage": [],
  "createdAt": "2025-01-15T10:30:00Z",
  "proof": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Add Storage Container

Add a storage container to an existing provisioning session in setup state. The {id} in the endpoint path is the provisioning session ID returned when the session was created.

Input

Endpoint

https://platform.{ESS Domain}/admin/provision/{id}/storage

Method

PUT

Authorization

An access token for a Service Account that has write access to the provision endpoints.

Content-Type

application/json

Payload

An empty JSON object {} or object with storage configuration.

Example Request

PUT /admin/provision/a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c/storage HTTP/1.1
Host: platform.example.com
Authorization: DPoP xxxxxxxx
DPoP: <proof-of-possession-token>
Content-Type: application/json

{}

Output

Returns the updated provisioning session with the new storage container added.

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c",
  "state": "setup",
  "webid": [
    "https://id.example.com/johndoe"
  ],
  "storage": [
    "https://storage.example.com/a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c/"
  ],
  "createdAt": "2025-01-15T10:30:00Z",
  "proof": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Storage Limits

By default, each provisioning session is limited to 10 storage containers. Attempting to exceed this limit will result in a 400 Bad Request response. This limit can be modified via configuration.

Get Provisioning Status

Retrieve the current status and details of a provisioning session.

Input

Field

Value

Endpoint

https://platform.{ESS Domain}/admin/provision/{id}

Method

GET

Authorization

An access token for a Service Account that has write access to the provision endpoints.

Example Request

GET /admin/provision/a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c HTTP/1.1
Host: platform.example.com
Authorization: DPoP xxxxxxxx
DPoP: <proof-of-possession-token>

Output

Returns complete details of the provisioning session including current state, resources, and stored proof data.

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c",
  "state": "setup",
  "webid": [
    "https://id.example.com/johndoe"
  ],
  "storage": [
    "https://storage.example.com/a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c/"
  ],
  "createdAt": "2025-01-15T10:30:00Z",
  "proof": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Activate Provisioning Session

Activate a provisioning session, transferring ownership from Service Account to the end user. This immediately revokes all Service Account privileges for the resources.

Input

Field

Value

Endpoint

https://platform.{ESS Domain}/admin/provision/{id}/activate

Method

PUT

Authorization

An access token for a Service Account that has write access to the provision endpoints.

Example Request

PUT /admin/provision/a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c/activate HTTP/1.1
Host: platform.example.com
Authorization: DPoP xxxxxxxx
DPoP: <proof-of-possession-token>

Output

Returns confirmation that the session has been activated and Service Account access has been revoked.

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c",
  "state": "active",
  "createdAt": "2025-01-15T10:30:00Z",
  "activatedAt": "2025-01-15T10:45:00Z",
  "proof": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Note

Activation is atomic and irreversible. Once activated:

Service Account immediately loses all access to user resources
Resources cannot return to setup state
Additional storage cannot be added via admin API
Only the end user can access their resources, as well as third-party agents for which Access Grants have been issued during provisioning

Deprovision Resources

Remove a provisioning session and all associated resources. Only available for sessions in setup state.

Input

Field

Value

Endpoint

https://platform.{ESS Domain}/admin/provision/{id}

Method

DELETE

Authorization

An access token for a Service Account that has write access to the provision endpoints.

Example Request

DELETE /admin/provision/a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c HTTP/1.1
Host: platform.example.com
Authorization: DPoP xxxxxxxx
DPoP: <proof-of-possession-token>

Output

Returns 204 No Content on successful deprovisioning.

Example Response

HTTP/1.1 204 No Content

Important Prerequisites for Deprovisioning

Before deprovisioning a non-active account, ensure that:

All Storage resources created during setup are deleted
All Access Credentials issued on behalf of the user are revoked

Deprovisioning permanently deletes the WebID, storage containers, and all associated data. This operation cannot be undone and is only available for sessions in setup state.

Error Responses

The Platform Management API uses standard HTTP status codes and RFC 7807 Problem Details format for error responses.

Common Error Responses

401 Unauthorized

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Valid authentication required"
}

403 Forbidden

{
  "title": "Forbidden",
  "status": 403,
  "detail": "Service Account not authorized for admin operations"
}

400 Bad Request - Invalid Input

{
  "title": "Bad Request",
  "status": 400,
  "violations": [
    {
      "field": "userData.username",
      "message": "Username cannot be empty"
    }
  ]
}

400 Bad Request - Storage Limit

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Storage limit exceeded. Maximum allowed: 10"
}

400 Bad Request - Invalid State Transition

{
  "title": "Bad Request", 
  "status": 400,
  "detail": "Cannot add storage to account in state: ACTIVE"
}

Service Account Access During Setup Phase

While resources are in setup state, Service Accounts have elevated privileges to perform operations on behalf of users:

Storage Operations

Service Accounts can create containers, upload files, and manage permissions:

PUT https://storage.example.com/a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c/document.ttl
Authorization: DPoP <service-account-token>
DPoP: <proof-of-possession-token>
Content-Type: text/turtle

<> a <http://example.org/Document> ;
   <http://example.org/createdBy> "service-account" .

WebID Management

Service Accounts can read and update WebID documents:

PUT https://id.example.com/johndoe
Authorization: DPoP <service-account-token>
DPoP: <proof-of-possession-token>

Access Credential Issuance

Service Accounts can issue Access Credentials on behalf of users during the setup phase, allowing third parties to access user resources according to specified permissions. When issuing credentials, the credential.credentialSubject.id must be set to the user's WebID:

POST https://accessgrant.example.com/issue
Authorization: DPoP <service-account-token>
DPoP: <proof-of-possession-token>
Content-Type: application/json

{
  "credential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://schema.inrupt.com/credentials/v1.jsonld"
    ],
    "type": ["VerifiableCredential"],
    "credentialSubject": {
      "id": "https://id.example.com/johndoe",
      "hasConsent": [{
        "mode": ["http://www.w3.org/ns/auth/acl#Read"],
        "forPersonalData": [
          "https://storage.example.com/a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c/foo/bar"
        ],
        "isConsentForDataSubject": "https://id.example.com/johndoe",
        "hasStatus": "https://w3id.org/GConsent#ConsentStatusRequested",
        "forPurpose": "https://example.com/SpecificPurpose"
      }]
    }
  }
}

Complete Provisioning Workflow

Here's a complete example of provisioning a user account:

Step 1: Create User Account

POST /admin/provision
{
  "userData": {
    "username": "johndoe"
  },
  "proof": "compliance-proof-data"
}

Response: Session created in setup state with WebID

Step 2: Add Storage

PUT /admin/provision/a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c/storage
{}

Response: Storage container added to session

Step 3: Configure Resources

Service Account can now access and configure user resources:

Create containers in storage
Upload initial data
Configure WebID profile
Issue Access Credentials for third parties

Step 4: Activate Account

PUT /admin/provision/a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c/activate

Response: Account activated, Service Account access revoked, user gains full control

Configuration

The Platform Management service requires several configuration options for proper operation.

Required Configuration

INRUPT_PLATFORM_HTTP_BASE_URL

The base URL for the Platform Management service HTTP endpoints.

INRUPT_PLATFORM_HTTP_BASE_URL=https://platform.{ESS_DOMAIN}

INRUPT_PLATFORM_ACCOUNT_PROVISION_SERVICE_USERNAME

Required. Username for the initial Service Account. The service will automatically create this Service Account on startup if it does not already exist. Once created, the username cannot be changed. If not set, the service will fail to start.

INRUPT_PLATFORM_ACCOUNT_PROVISION_SERVICE_USERNAME=provision-service

Optional Configuration

INRUPT_PLATFORM_STORAGE_MAX_LIMIT

Maximum number of storage containers allowed per provisioning session.

Default: 10

INRUPT_PLATFORM_STORAGE_MAX_LIMIT=10

Important: Storage Limit Consistency

This value must be set to the same value as:

INRUPT_STORAGE_MAX_PODS_PER_OWNER
INRUPT_AUTHORIZATION_MAX_POD_COUNT

Eventually, INRUPT_PLATFORM_STORAGE_MAX_LIMIT will be the primary configuration option, with the others retained for backwards compatibility only.

INRUPT_AUTHORIZATION_RELATIONSHIP_RETENTION_WINDOW_ENABLED

Controls whether the relationship cleanup task is enabled for removing soft-deleted relationships.

Default: true

INRUPT_AUTHORIZATION_RELATIONSHIP_RETENTION_WINDOW_ENABLED=true

INRUPT_AUTHORIZATION_RELATIONSHIP_RETENTION_WINDOW_DURATION

Duration to retain soft-deleted relationships before permanent deletion. Uses ISO 8601 duration format.

Default: P30D (30 days)

INRUPT_AUTHORIZATION_RELATIONSHIP_RETENTION_WINDOW_DURATION=P30D

INRUPT_AUTHORIZATION_RELATIONSHIP_RETENTION_WINDOW_BATCH_SIZE

Maximum number of relationships to delete per batch operation. Must be greater than 0.

Default: 500

INRUPT_AUTHORIZATION_RELATIONSHIP_RETENTION_WINDOW_BATCH_SIZE=500

INRUPT_AUTHORIZATION_RELATIONSHIP_RETENTION_WINDOW_TASK_EVERY

Duration between cleanup task executions. Uses ISO 8601 duration format.

Default: PT6H (every 6 hours)

INRUPT_AUTHORIZATION_RELATIONSHIP_RETENTION_WINDOW_TASK_EVERY=PT6H

Audit Events

The Platform Management service emits comprehensive audit events for all administrative operations to ensure compliance and accountability. These events are sent to the Audit service and contain detailed information about the actions performed by Service Accounts.

Event Types

Account Created Event

Event Name: admin-account-created Event Type: Create Description: Fired when a Service Account creates a new provisioning session

Event Details:

Actor: Service Account WebID performing the operation
Attributed To: End user's WebID (account being created)
Object: Provisioning session URI, WebID document, and storage containers
Instrument: Compliance proof data (if provided)
Result: Success status and account state information

Account Activated Event

Event Name: admin-account-activated Event Type: Update Description: Fired when a Service Account activates a provisioning session, transferring ownership to the end user

Event Details:

Actor: Service Account WebID performing the operation
Attributed To: End user's WebID (account being activated)
Object: Provisioning session URI, WebID document, and storage containers
Instrument: Compliance proof data
Result: Success status with confirmation that admin access was removed

Account Deprovisioned Event

Event Name: admin-account-deprovisioned Event Type: Delete Description: Fired when a Service Account deprovisions a session and removes all associated resources

Event Details:

Actor: Service Account WebID performing the operation
Attributed To: End user's WebID (account being deprovisioned)
Object: Provisioning session URI, WebID document, and storage containers
Instrument: Compliance proof data
Result: Success status with confirmation that all resources were removed

Audit Event Structure

Each audit event includes the following standard components:

Actor: The Service Account performing the administrative action
Attributed To: The end user on whose behalf the action is performed
Object: All affected resources (provisioning session, WebID, storage containers)
Instrument: Any compliance proof or evidence associated with the operation
Result: Operation outcome and relevant status information

Example Audit Event

Here is an example of an admin-account-created audit event:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://schema.inrupt.com/audit/v1.jsonld"
  ],
  "id": "urn:uuid:85fcb915-29a4-4e0f-bf3a-27ed4c13f559",
  "type": [
    "Activity",
    "Create"
  ],
  "name": "admin-account-created",
  "summary": "Admin agent created account on behalf of user",
  "generator": {
    "wasAssociatedWith": "ess-platform-management-7fccddb8bf-2rssk",
    "type": [
      "SoftwareApplication"
    ],
    "qualifiedAssociation": "79",
    "name": "inrupt-platform-management-postgres",
    "id": "https://platform.example.com/"
  },
  "actor": [
    {
      "id": "https://id.example.com/service-account"
    }
  ],
  "attributedTo": [
    {
      "id": "https://id.example.com/johndoe",
      "name": "johndoe"
    }
  ],
  "object": [
    {
      "type": [
        "object"
      ],
      "content": "account_id=a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c,state=setup",
      "id": "https://platform.example.com/admin/provision/a7f8b9c2-4d5e-6f7a-8b9c-1d2e3f4a5b6c",
      "name": "johndoe"
    },
    {
      "id": "https://id.example.com/johndoe",
      "type": [
        "WebID"
      ],
      "name": "WebID Document"
    }
  ],
  "instrument": [
    {
      "name": "Account Provision Proof",
      "content": "compliance-proof-data"
    }
  ],
  "result": [
    {
      "content": "status=success",
      "type": [
        "object"
      ],
      "name": "Provisioning Result"
    }
  ],
  "identifier": "93c270cbbc9a8fa9c413210ba028e03d",
  "published": "2025-01-15T10:30:00Z"
}

This example shows:

Actor: The Service Account (https://id.example.com/service-account) performing the operation
Attributed To: The end user (https://id.example.com/johndoe) on whose behalf the account is created
Object: The provisioning session and WebID document that were created
Instrument: The compliance proof provided during account creation
Result: Success status of the provisioning operation

Additional Service Audit Events

Other ESS services (Storage and Access Grant services) will emit their existing audit events to record Service Account actions during the provisioning process. This provides comprehensive audit coverage across all system components:

Storage Service Events: Record storage container creation, data ingestion, and resource management performed by Service Accounts
Access Grant Service Events: Record credential issuance and access grant operations performed on behalf of users
Authorization Service Events: Record permission changes and access control updates during setup and activation phases

Compliance Integration

Audit events support compliance workflows by:

Recording all administrative actions with timestamps
Tracking the delegation relationship between Service Accounts and end users
Including compliance proof data in event records
Providing clear attribution and accountability trails
Supporting regulatory requirements for data handling and user consent
Providing comprehensive audit coverage across all ESS services involved in provisioning

These audit events can be consumed by compliance monitoring systems, SIEM platforms, or other audit log aggregation tools to maintain comprehensive records of all Platform Management operations and related service activities.

Additional Information

See also Quarkus Configuration Options for additional service configuration options.

PreviousPlatform Management Services NextPurger Service

Last updated 3 days ago