Skip to main content

Data Intermediation Service Provider APIs

The following steps outline how developers can integrate iGrant.io data intermediation services to expose consumer personal data within their organisations. This guide is intended for those looking to incorporate:
  • Digital wallets into their applications.
  • Consent management into their applications using digital wallets.

Step 1: Get the API Key​

To get your API key, sign in to the dashboard and go to Account > Developer APIs > Create API Key (see Get API Keys).

Step 2: Define a Data Agreement​

During this step, data agreements are defined for any processing of personal data. This processing may involve exposing data as a data source (Issuer of the data) or consuming data as a data-using service (Verifier of the data). This can be achieved through a Data Protection Impact Assessment (DPIA) or a similar process to ensure robust data usage in compliance with applicable data regulations, such as GDPR.

To create a data agreement, copy the request body below and send it to the create data agreement API (POST /v4/config/consent/data-agreement). This example is for a data source, so methodOfUse is data_source and dataExchange refers to the credential definition that the data agreement issues (dataExchangeProfile is OID4VC and id is the credentialDefinitionId). For a data-using service, set methodOfUse to data_using_service and put the presentationDefinitionId in dataExchange.id. The credential or presentation definition must already exist, because the service only reads it and does not create it.

{
  "dataAgreement": {
    "controllerName": "Example Bank",
    "controllerUrl": "https://example.com",
    "policy": {
      "name": "Privacy policy",
      "version": "1.0",
      "url": "https://example.com/privacy-policy",
      "jurisdiction": "Sweden",
      "industrySector": "Banking",
      "dataRetentionPeriodDays": 365,
      "geographicRestriction": "EU",
      "storageLocation": "EU",
      "thirdPartyDataSharing": false
    },
    "purpose": "Issue a customer credential",
    "purposeDescription": "Issue a verifiable credential with the customer data to the wallet of the customer.",
    "lawfulBasis": "consent",
    "methodOfUse": "data_source",
    "dpiaDate": "2026-11-01T10:00",
    "dpiaSummaryUrl": "https://example.com/dpia-summary",
    "active": true,
    "forgettable": false,
    "dataExchange": {
      "dataExchangeProfile": "OID4VC",
      "id": "<credentialDefinitionId>"
    },
    "dataAttributes": [
      { "name": "identifier", "description": "Registration number of the company", "sensitivity": false, "category": "Identity", "restrictions": [] },
      { "name": "legalName", "description": "Legal name of the company", "sensitivity": false, "category": "Identity", "restrictions": [] }
    ]
  }
}

Step 3: Integrate Data Wallet SDK​

This step integrates the iGrant.io digital wallet SDKs into existing Android and iOS applications, enhancing them with decentralised application (dApp) capabilities and digital wallet functionalities.

This step integrates the iGrant.io consent management (Privacy Dashboard) SDKs into existing Android and iOS applications, introducing privacy dashboard capabilities that enable individuals to exercise their rights under data regulations such as GDPR.

Step 5: Implement DISP APIs​

The organisation wallet issues and verifies credentials using OpenID4VCI 1.0 and OpenID4VP 1.0. There is no need to set up a connection with the individual's wallet first: the wallet simply receives a credential offer or a verification request as a QR code or a link.

Issue/expose data (Data Source)​

The process of issuing (or exposing) data allows organisations to securely manage the credential issuance workflow with data consents. Here is a step-by-step overview:

  1. Create Data Agreement to Issue Credential: Organisation A starts the process by creating a data agreement (Step 2). This agreement outlines the terms under which credentials are issued as per ISO27560 and refers to the credential definition to issue. The data agreement could be formulated based on a Data Protection Impact Assessment (DPIA) and follows the framework defined in this IEEE paper.
  2. Issue a Credential for the Data Agreement: Based on the data agreement, Organisation A issues a credential to the individual's wallet. Send the dataAgreementId instead of a credentialDefinitionId to the issue credential API (POST /v4/config/ows/issuer/issuance-history). The API finds the credential definition through the data agreement, and the issuer adds the data agreement to the claims of the credential. The response contains the credential offer (offer.uri) for the individual's wallet, as in Issue Credential (In-Time).
{
  "dataAgreementId": "<dataAgreementId>",
  "mode": "in_time",
  "preAuthorised": true,
  "urlScheme": "openid-credential-offer://",
  "credentials": [
    {
      "credentialConfigurationId": "<credentialConfigurationId>",
      "claims": { "identifier": "000", "legalName": "Bygg AB, Sweden" }
    }
  ]
}
  1. Notify Issuance State Through Webhook Events: As the issuance progresses, Organisation A is notified through webhook events. The issuer sends an ows.issuer.issuance_history.* event at each stage, for example ows.issuer.issuance_history.credential_issued once the credential is issued. See Webhook Events.

This workflow enables organisations to manage the distribution of digital credentials efficiently, while keeping each issuance tied to a data agreement.

Verify/consume data (Data Using Service)​

The process of verifying (or consuming) data allows organisations to manage the data consumption workflow with digital wallet based verifications. Here is a step-by-step overview:

  1. Define Data Agreement to Verify Credential: Organisation A sets up a data agreement (Step 2, with methodOfUse set to data_using_service) that stipulates the criteria under which credentials will be verified. The data agreement policy is based on ISO27560 and can use any lawful basis of processing, including consent.
  2. Send a Verification Request: Organisation A creates a presentation definition and a verification request, then shares the request URL with the individual's wallet as a QR code or a link. See Send and Verify Credential.
  3. Notify Verification State Through Webhook Events: Once the individual responds, Organisation A receives a webhook event, for example ows.verifier.verification.presentation_received, and can proceed with data-related decisions based on the verified credentials. See Webhook Events.