Introduction

The Athumi Pod-Platform offers functionality helping solid adopters with certain aspects linked to the solid ecosystem integration.

Key features include

  • WebId and Pod management

  • Validations

  • Contract & data management

Concepts

WebId

A WebID is a URI that uniquely identifies a person, organization, or other entity on the web. The URI points to a profile document describing the person or entity, including various attributes and relationships to other entities, all represented using Linked Data principles.

Example https://webid.burgerprofiel.vlaanderen.be/profiles/e625fb09-e135-4067-8b32-99a902c86046

@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

<https://webid.burgerprofiel.dev-vlaanderen.be/profiles/e625fb09-e135-4067-8b32-99a902c86046>
  a foaf:Agent;
  <http://www.w3.org/ns/solid/terms#oidcIssuer> <https://pod-platform.api.dev-athumi.eu/openid> ;
  <http://www.w3.org/ns/pim/space#storage>      <https://storage.sandbox-pod.datanutsbedrijf.be/e89352b2-6699-4891-ae95-74c36b0e9d13/> .

WebId profile predicates that are important include

Predicate Meaning

http://www.w3.org/ns/solid/terms#oidcIssuer

The OIDC issuer(s) allowed to issue Solid OIDC tokens for this WebId

http://www.w3.org/ns/pim/space#storage

The pod storage space(s) associated with this WebId.

WebIds managed by the Pod-Platform can only have one pod storage space associated with them.

Other predicates can be added but are not interpreted or used by the API

See WebId management for more information on how to manage WebIds using the API.

Contract

A contract is an RDF representation of the following data:

  • Which datatype is being requested for access

  • Who is requesting access to this data

  • What is the purpose for requesting access

  • For what period is access being requested

A contract represents the outcome of a legal agreement within a defined governance framework and will be used to create a Access Grant granting permissions to a POD resource.

See Contracts for more information on how to use Contracts with the API.

Correlation-id

The X-Correlation-Id header is required in each request to the API, and plays an important role in correlating client requests for tracking and troubleshooting purposes.

  • X-Correlation-Id: This header is used to uniquely identify a transaction or a chain of events across multiple services. By passing the same X-Correlation-Id across related requests, the client can correlate operations within a workflow, making it easier to monitor and trace requests across distributed systems. If the client does not provide this header, a correlation ID will be automatically generated by the system and included in the response.

This header is included in the API response, allowing the client to track the lifecycle of requests and responses.

Access Grant

An Access Grant in the ecosystem is a digital permission document that allows an entity (such as a person, organization, or service) to access specific resources stored within a POD.

Verifiable Credential

A Verifiable Credential (VC) is a digital representation of information that can be cryptographically verified to prove its authenticity, integrity, and ownership. Verifiable credentials are part of the decentralized identity model, allowing individuals or entities to present proof of specific claims (e.g., identity, ownership, or authorization) without relying on a centralized authority.

Each verifiable credential typically consists of three key components:

  • Issuer: The entity or organization that issues the credential and attests to the information contained within it. For example, a government body may issue a verifiable credential proving a person’s citizenship.

  • Holder: The individual or entity that possesses the verifiable credential and can present it to others when needed. In decentralized systems, holders store these credentials in digital wallets.

  • Verifier: The entity or system that checks the validity of the credential. By verifying the cryptographic signatures embedded within the VC, the verifier ensures the credential has not been tampered with and that it was issued by a trusted party.

See https://www.w3.org/TR/vc-data-model-2.0/ for more information.

POD

A POD (Personal Online Data Store) is a secure, decentralized storage unit where individuals have complete control over their data.

Consent Capture Application

The Consent Capture Application (CCA) is designed to securely collect, manage, and store consent from individuals, ensuring that organizations comply with data privacy regulations and provide users with control over their personal data.

Linked data

The following RDF artefacts are available on the pod platform.

Vocabularies / Ontologies

URL Content

https://pod-platform.api.athumi.eu/doc/vocabulary/core.ttl

The core pod platform vocabulary

JSON-LD schemas

URL Content

https://pod-platform.api.athumi.eu/doc/context/2024-10-08/contract.jsonld

The contract JSON-LD context

Data type definitions

URL Content

https://pod-platform.api.athumi.eu/doc/conceptscheme/data-type.ttl

Base data type concept definition

https://pod-platform.api.athumi.eu/doc/concept/data-type/2024-05-22/diploma.ttl

Diploma data type definition

https://pod-platform.api.athumi.eu/doc/concept/data-type/2024-06-01/studentenattest.ttl

"Studentenattest" data type definition

Security

JWT based authentication

The pod Platform API uses JWTs for authentication and authorization.

2 types of tokens are currently supported

  • Solid OIDC tokens

  • (deprecated) JWS tokens

The individual endpoints documented in swagger provide additional info on the use of the JWTs

Solid OIDC token

The Pod-Platform API uses Solid OIDC tokens for authentication and authorization.

A solid OIDC compliant token is a token that is issued by a OIDC compliant identity provider containing the following claims:

Claim Required Type Description

webid

Yes

URI

The WebID of the party identified by the token

citizen_national_id(*)

No

String

The citizen’s national identifier (e.g: Rijksregisternummer for Belgium)

iss

Yes

URI

The token issuer

aud

Yes

Array of strings or single string value

The audience claim should at least contain the value solid

client_id

No

URI or UUID

The client id used to identify the calling application / system

exp

Yes

Date-time

The expiration time identifies when the JWT expires.

Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

iat

Yes

Date-time

Timestamp at which the JWT was issued, must be in the past.

Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

(*) The citizen_national_id claim is required for the WebId (GET and PUT) related API calls

(Deprecated) JWS tokens

The use of JWS tokens is deprecated and will be removed in a future version of the Pod-Platform API.

Claim Required Type Description

citizen_national_id

Yes

String

The citizen’s national identifier (e.g: rijksregisternummer for Belgium)

iss

Yes

URI

The token issuer

azp(*)

No

URI or UUID

The authorized party used to identify the calling application / system

client_id(*)

No

URI or UUID

The client id used to identify the calling application / system

exp

Yes

Date-time

The expiration time identifies when the JWT expires. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

iat

Yes

Date-time

Timestamp at which the JWT was issued, must be in the past. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

(*) Either one of azp or client_id is required

Signing

The JWT must be signed by one of the key pairs of which the public keys are present in the issuer’s JWKS.

The header of the JWT should contain the following claims

Claim Required Description

typ

Yes

Should always be jwt

alg

Yes

Algorithm used for signing

kid

No

The identifier of the key that was used to sign the JWT

OpenApi spec & Swagger

WebId

See WebId concept for additional information on WebIds.

WebIds managed by the API are associated with civilians. A civilian can be identified using a citizen national identifier (e.g. Rijksregisternummer for Belgium). This national identifier is passed implicitly in the security token used to access the API.

Executing the request with an Authorization header set to

Bearer eyJraWQiOiJkYWI5YWUyNS0wNzFhLTQ3MmQtYWYwNi0yOTlmYmNmYmQ4Y2QiLCJ0eXAiOiJqd3QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJhNTJlMzU4ZC04ZGMzLTQ0YjQtYWQ0My0xZDdlYjBmNDE3YzEiLCJhenAiOiI4YTJhZGRiYi0zM2U2LTRkYzYtYTNkNC03ZjZmOGY3MWU3Y2EiLCJpc3MiOiJodHRwczovL3BvZC1wbGF0Zm9ybS5hcGkuZGV2LWF0aHVtaS5ldS9vcGVuaWQiLCJjaXRpemVuX25hdGlvbmFsX2lkIjoiNzE2OTA5OTk4MjciLCJleHAiOjE3MjE3NDM3NjIsImlhdCI6MTcyMTY1NzM2MiwianRpIjoiNjllMTUwNmQtNGQxYS00OGNhLWI5ZjYtZDM5YzhkZjBkODFlIn0.WmIiic5NPv3eHBpbXa1QE2Qw83JewsEmc2zhbKcODz6GIV8SXjmSe7-3--lZyFkSv7RIgfgllIWTG5-W934lSe09MbZoe9mbUKj185fLNc1CWFrf8W1RHoKZF1_W9HpkY7ilDkcACQKRpaI7X9dwuUTGtcThNwhQmkVtBoZhOrtgABtyptBATmMjGqwTve94ICVsptMA8udLpB4PnEDi_uOyFi-9XZwFs8cQKSM4BI_q9IuwV-Y1yo9yw16RIifEnotgd1MSuxIcuQi4tL2JGPWbrunuV3Ys7wIVLPXBNKKOsLwxTGq-10We4hcN1M2eGlwUn1NQ6WZtEKD5MIrrag

Decoded token:

{
  ...
  "citizen_national_id": "71690999827",
  ...
}

Will issue the request for the civilian with national identifier 71690999827.

Get the WebID for a citizen

You can use the REST API to retrieve the WebId of a citizen managed by the Pod-Platform. A WebId enables you to identify a citizen within the Solid ecosystem. For more information, see "WebId concept"

The api requires a Token with a citizen_national_id claim to identify the citizen.

WebIds can be retrieved using the GET WebId endpoint.

Create the WebID and corresponding pod for a citizen

You can use the REST API to create a WebId and a corresponding POD for a citizen within the Pod-Platform. A WebId enables you to identify a citizen within the Solid ecosystem. For more information, see "WebId concept"

The api requires a Token with a citizen_national_id claim to identify the citizen.

WebIds can be created using the PUT /v1/webids endpoint.

  • Responses:

    • 200 - OK: An existing WebId was found

    • 201 - CREATED: A new WebId was created

Delete the WebID and corresponding pod for a citizen

You can use the REST API to create a WebId and a corresponding POD for a citizen within the Pod-Platform.

The api requires a Token with a citizen_national_id OR webid claim to identify the citizen.

Contract & Data

You can use the REST API to retrieve a contract, citizen data based on a contract or store citizen data in a POD based on a contract. For more information, see "Contract"

Retrieve a contract

You can use the REST API to retrieve a RDF representation in json-ld of the contract managed by the Pod-Platform. The contract specifies which citizen data can be retrieved and stored.

The API requires no authentication to retrieve a contract.

A contract can be retrieved using the GET /contracts/{contractId} endpoint.

Retrieve a list of citizen data

A CCA can use the REST API to retrieve a list of citizen data in the context of a contract.

A list of personal data for the citizen, of the types defined in the contract, is represented as dataValues objects.

When an error is present within a data value, it is not eligible for further processing. It can be shown to the citizen by the CCA, but the CCA should not allow the citizen to select it.

For each data value, a summary is generated from the raw data, including the mandatory fields that a CCA is obligated to present. The fields within the summary contain a format field that indicates how the value should be rendered in the view.

Format Description

string

One or more internationalized string items.

group

A grouped field with a map of other fields.

date

A string value that must be formatted as a date.

timestamp

A string value that must be formatted as a timestamp.

boolean

A string value that must be formatted as a boolean.

number

A string value that must be formatted as a number.

error

There was an error with this field when generating the summary. The value is an internationalized error message.

The api requires a Solid OIDC token with the webid identifying the citizen.

Citizen personal data can be retrieved using the GET /contracts/{contractId}/data endpoint.

Share citizen data

You can use the REST API to share specific citizen data with the data user under the terms of a given contract. The data is stored in the citizen’s POD as a Verifiable Credential. The data user is granted access to the resource through a access grant, which specifies the mode, duration, and purpose, as outlined in the contract.

The api requires a Solid OIDC token with the webid identifying the citizen.

Citizen personal data can be shared using the POST /contracts/{contractId}/data endpoint.

Read citizen data

Data consumers can use the REST API to read resources previously shared by a citizen. They only need the access grant that was issued during the data share flow.

Data can be read by the consumer using the GET /v1/resources endpoint.

The API requires a Solid OIDC token with the webid identifying the data consumer (e.g. https://dev-tools.pod-platform.acc-athumi.eu/webid/profile/acme.ttl).

Note: This endpoint can also be used outside the contract context. If a consumer has an access grant pointing to a single resource they can also use this API. In that case they don’t need to implement the UMA flow to access to the resource.

Verification

Verify WebID Ownership via Business Key

Data consumers can use the REST API to validate the ownership of a WebId based on a specified business key.

The api requires a Solid OIDC token with the webid identifying the data consumer.

  • Request:

    • businessKey: An object that specifies the type and value of the business key for verification. The business key type for initial support is NATIONAL_NUMBER_BE.

    • accessGrantVc: A plain string that contains the access grant verifiable credential, providing proof of authorization to perform the verification.

  • Responses:

    • the webId retrieved within the accessGrantVc credentialSubject.id is linked to the citizen identified by the businessKey results in 200 - ok. response body valid is 'true'

    • the webId retrieved within the accessGrantVc credentialSubject.id is not linked to the citizen identified by the businessKey results in 200 - ok. response body valid is 'false'

    • the accessGrantVc is not valid results in 400 - bad request

    • the accessGrantVc status does not match 'ConsentStatusExplicitlyGiven' results in 400 - bad request

    • the SOLID-oidc id token is not valid results in 403 - forbidden

A business key can be verified using the POST /v1/verifications/business-key endpoint.

Data copies

When a data consumer has the permission to store a local copy, he is obligated to report which resources are stored. Per resource and purpose an entry will be saved for auditing purposes.

Add local copy entry

Data consumers can use the REST API to report that a resource is stored as a local copy.

The api requires a Solid OIDC token with the webid identifying the data consumer.

A local-copy can be reported using the POST /v1/data-copies endpoint.

Mark a local copy as deleted

The data consumer is obligated to delete the local copy of the data under the following conditions:

  • Expiration date of the active Access Grant is Expired.

  • Status (ESS) of the active Access Grant is Revoked.

  • The active Access Grant is invalid.

  • If the resource of the active Access Grant is not present.

  • If the verifiable credential is invalid. This can be because it has been revoked, it has expired or the signature has become invalid.

To ensure these conditions are met, implement periodic polling at an interval agreed upon with Athumi. This ensures timely deletion of data that no longer meets the criteria for retention. Upon deletion of data based on the above criteria, notify the designated endpoint about the deleted resources. This is essential for compliance and auditability. The polling interval must be established in collaboration with Athumi to ensure operational harmony and compliance effectiveness.

The api requires a Solid OIDC token with the webid identifying the data consumer.

Data consumers can use the DELETE /v1/data-copies endpoint to report that a resource is not longer stored as a local copy.

Change log

  • 2024-07-01: Initial version