SSI Issuance Integration

Introduction

Objective

This document explains how to integrate Gataca’s SSI Credential Issuance Service into your infrastructure. The integration allows your system to issue Verifiable Credentials (VCs) in line with W3C DID and Verifiable Credentials standards.

Target Audience

Developers, solution architects, and system administrators responsible for integration.

Key Benefits

• Issue interoperable Verifiable Credentials.

• Adhere to international SSI standards.

• Ensure data security and decentralized control.

Prerequisites

• Internet access to consume the exposed APIs over HTTPS.

• Ports: 443 (TLS/SSL).

Integration Workflow

The following steps outline the workflow for credential issuance:

1. The client sends a credential issuance request to the API.

2. The API validates the request and processes the data.

3. The backend issuer generates the Verifiable Credential.

4. The API provides the new credential.

Sequence Diagram

User Wallet: Gataca .

Relying Party App (also known as a service provider): refers to the web or mobile application that requires authentication from a user - this is your organization.

Certify: Issuance component in Gataca Studio

Sequence Diagram

API Endpoints

Detailed API endpoint documentation (including request/response formats, parameters, and error codes) is provided in the Swagger documentation.

Swagger UI

Step-by-Step Integration Guide

Initial Configuration

1. Generate API Key

Log in to the Gataca Studio portal and generate an API key, ensuring it is linked to a specific Issuance Template if required. Once the API key is successfully generated, click the Save button to confirm the configuration.

Gataca Studio - Generating API Key

2. Obtain API Key Credentials

After generating the API key, the associated credentials will be displayed. Store this information securely, as it will be required for authenticating requests to the platform. Note that the credentials may not be retrievable again.

Gataca Studio - API Key Credentials

Authentication

The majority of Gataca endpoints are protected to avoid unauthorized access and security issues. This protection is based on access tokens issued using basic authentication.

3. Obtain an Access Token

Use the platform’s login endpoint to retrieve an Access Token. This token is required to authenticate and authorize all protected operations within the system. Make sure to securely store the token for subsequent API requests.

Request Example

http

POST /admin/v1/api_keys/login
Host: nucleus.gataca.io
Authorization: Basic [API-KEY-CREDENTIALS]
tenant: [TENANT]
ssiconfig: [TEMPLATE-ID]
Content-Type: application/json

API-KEY-CREDENTIALS: base64(api-key id:api-key secret) - You must provide the API Key ID (UUID) and secret given when creating the API Key in Studio, encoded in base64 format in the HTTP request header.

TENANT: A tenant is a logical instance that isolates data and configurations, identified by a unique tenant ID to ensure separation from other clients.

TEMPLATE-ID: Identifier of the template used for this verification. These identifiers are configured in Studio.

Response Example

http

HTTP/1.1 200 OK
Content-Type: application/json
Token: ACCESS-TOKEN
Token_type: jwt

{
    "message": "SUCCESS"
}

Details: Swagger

Issuing a Credential

To generate a Verifiable Credential and uniquely associate it with a subject, the subject must first be identified. This requires an issuance process, where the subject’s identity is validated through a DID (Decentralized Identifier). Optionally, additional data such as email, phone number, or ID card can also be validated, allowing the issuing entity to reliably identify the subject.

Once the subject provides this information, the issuer must validate the submitted data. After successful validation, the issuer can proceed to issue the new credential

4. Generating Issuance Process instance

Request Example

http

POST /api/v3/oidc-issuance/credential-offer
Host: certify.gataca.io
Authorization: jwt [ACCESS-TOKEN]
Content-Type: application/json

{
    "group":"ISSUANCE-TEMPLATE-ID"
}

• ACCESS-TOKEN: Access token received from the login request (This authentication must be executed by an application linked to that TENANT, not an administrator).

• SSI-TEMPLATE-ID: Identifier of the template used for this issuance. These identifiers are configured in Studio.

Response Example

http

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

{
    "additionalData": "vidCredential",
    "callback": "https://certify.gataca.io",
    "id": "2xuEMaSrrxsTMyaioJuSMKejfCyBim7g",
    "nonce": "25rbiezf6aKoZzRLkfLYH72DgYWDwdNG",
    "proof": [
        {
            "challenge": "31CAw5WKkZk3dFfwGv32WgLddchHUonf",
            "created": "2021-06-07T10:24:28Z",
            "creator": "did:gatc:29YTmCCBDg...Wrs8zkVs7s#keys-1",
            "domain": "gataca.io",
            "proofPurpose": "authentication",
            "proofValue": "jPwJKhJWUk...7ysbWJWUkJgmu7--",
            "type": "Ed25519Signature2018",
            "verificationMethod": "did:gatc:29YTmCCB...rs8zkVs7s#keys-1"
        }
    ],
    "requested": [
        {
            "mandatory": true,
            "purpose": "authentication",
            "trustLevel": 1,
            "type": "academicInstitutionCredential"
        }
    ]
}

This response is too large to be displayed in a QR code. Therefore, only the session ID (e.g., 2xuEMaSrrxsTMyaioJuSMKejfCyBim7g) is shown to represent the issuance process within the QR code. This session ID is essential for the next step, so please ensure you copy and save it.

The structure of the Verifiable Credential shows the credential type, the trust level (if the credential needs to be issued by a trusted issuer or it can be issued by any or self-attested), the purpose for requesting the credential, and if the credential is requested mandatorily or optionally.

The session generation step can be automatic using GatacaQR, a JavaScript component allowing any relying party to generate a session in a simple way.

You will find the GatacaQR component code repositories at the end of this documentation.

Details: Swagger

5. Validating the Issuance Process

Getting the information from a specific issuance process is also possible using the command below. Instead of getting the information from a set of issuance processes, this command gets the information from a specific issuance process (using the process identifier).

Request Example

http

GET /api/v3/tenants/gataca/oidc-issuance/credential-offer/[ISSUANCE-PROCESS-ID]
Host: certify.gataca.io
Authorization: jwt [ACCESS-TOKEN]
Content-Type: application/json

• ISSUANCE-PROCESS-ID: Issuance process identifier used by the end user to request new VCs.

• ACCESS-TOKEN: Access token received from the authentication call. (This authentication must be executed by an app related to that issuance process, not an administrator).

Response Example

http

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

{
  "id": "25shTZfXmens1EYrgLBoTZpSgNKUXnLt",
  "status": "ISSUED",
  "group": "dnidemo",
  "data": [{
    "credentialStatus": {
      "id": "https://certify.gataca.io:9090/api/v1/group/dnidemo/status",
      "type": "CredentialStatusList2017"
    },
    "credentialSubject": {
      "firstName": "Samuel",
      "id": "did:gatc:M2VhNjU2MzI...kOTdiNWMzZGI1"
    },
    "id": "cred:gatc:g6hn7m...nvd4ukr61j43d",
    "issuer": "did:gatc:32Zn2...yfVJvRcwikVFu1Pa",
    "type": [
      "VerifiableCredential",
      "firstNameCredential"
    ]
  }],
  "validator": {
    "id": "25shTZfXmens1EYrgLBoTZpSgNKUXnLt",
    "securityMechanisms": {
      "@context": [
        "https://www.w3.org/2018/credentials/v1"
      ],
      "proof": [],
      "type": [
        "VerifiablePresentation",
        "GatacaCredentialPresentation"
      ]
    },
    "verifiablePresentation": {
      "@context": [
        "https://www.w3.org/2018/credentials/v1"
      ],
      "proof": [{
        "created": "2020-10-09T08:12:46Z",
        "creator": "did:gatc:M2VhNjU2MzI3NT...WMzZGI1#keys-1",
        "proofPurpose": "authentication",
        "proofValue": "9tEN6NmIovJxk9v7gChoVy...HbckK8ZXh9tMrCQ",
        "type": "Ed25519Signature2018"
      }],
      "type": [
        "VerifiablePresentation",
        "GatacaCredentialPresentation"
      ],
      "verifiableCredential": [{
        "credentialSubject": {
          "email": "[e-mail]",
          "id": "did:gatc:M2VhNjU2...kOTdiNWMzZGI1"
        },
        "id": "cred:gatc:ZGU5NGQ4MzFi...TMzNWQwODky",
        "issuanceDate": "2020-10-07T10:15:03Z",
        "issuer": "did:gatc:acYseLtTEVeqF8...77uCKqyM3imEJH",
        "proof": [{
          "created": "2020-10-07T10:15:03Z",
          "creator": "did:gatc:24gsRbsURij3edo...hggrnR#keys-1",
          "proofPurpose": "authentication",
          "proofValue": "wpQJlNwZfHUNesE...2KpGt4ygTJfzdBA",
          "type": "Ed25519Signature2018"
        }],
        "type": [
          "VerifiableCredential",
          "emailCredential"
        ]
      }]
    }
  },
  "createdAt": "2020-10-09T08:12:29.134017Z",
  "updatedAt": "2020-10-09T08:24:54.53356Z"
}

Information structure

The response consists of the following components:

1. Issuance Process Metadata

   • Identifier: A unique identifier assigned to the issuance process.

   • Type: The type or category of the issuance process.

   • Dates: Timestamps indicating creation and update times for the process.

   • Status: The current state of the issuance process.

2. Status Definitions

   • PENDING: The session has been created, but no additional information has been associated with the process yet.

   • ISSUED: Verifiable Credentials (VCs) tied to the issuance process have been successfully downloaded.

   • REJECTED: The issuance process has been rejected by the issuer.

3. Data

   • This field contains the newly issued Verifiable Credentials provided by the relying party.

   • The field is populated only when the issuance process reaches an ISSUED status.

4. Validator

   • Includes all the information shared by the end user, as requested by the relying party, to complete the authentication process into Studio.

1. Generate Verifiable Credential

Once the Relying Party has validated the required information, it must issue the new Verifiable Credential (VC). This involves populating the data for the new VC based on the associated issuance process.

To complete this step, the Relying Party should call the following endpoint:

Request Example

http

PATCH /admin/v1/issuanceRequests/[ISSUANCE-PROCESS-ID]/credentials
Host: certify.gataca.io
Authorization: jwt [ACCESS-TOKEN]
Content-Type: application/json

[
  {
    "credentialSubject": {
      "documentType": "Passport",
      "firstName": "John",
      "lastName": "Doe",
      "identifier": "00000000X",
      "dateOfBirth": "25-05-1977"
    },
  }
] 

The schema for each verifiable credential type is stored in Studio. It is also possible to retrieve the schema from Studio responses (credential schema).

Each VC consists of the following components:

• credentialSubject: This is a map of fields that includes the values for the credential. Within this object, it is possible to attach the holder’s ID (DID) and define the properties specific to that type of credential.

You can also retrieve the holder’s DID from the earlier steps (Steps 14 and 21). This information is included in the validator property within the Presentation Response.

Reference Path: verifiablePresentation → proof → creator

Note: Ensure you remove the trailing part (#keys-n).

Example: did:gatc:M2VhNjU2MzI3NT...WMzZGI1

For each VC, the following details can be included:

• id (optional):

  • A unique identifier for the VC.

  • It MUST be unique, so generating a new random string for each VC is necessary.

• issuer (optional):

  • The DID of the entity issuing the VC.

• issuanceDate (optional):

  • The date when the VC was issued.

• validFrom (optional):

  • The date from which the VC becomes valid.

• credentialSchema (optional):

  • Specifies the schema used to issue the VC instead of relying on the type.

  • If provided, the type should be set as VerifiableID or VerifiableAttestation.

• evidence (optional):

  • A field to describe how the identification was verified prior to issuing the VC.

• context (optional):

  • Indicates the context used for issuing the VC.

  • Default contexts are provided, but these can be overridden if necessary.

If the Relying Party does not specify certain optional fields, Studio will automatically populate some of them based on default configurations.

The response is an array representing the issuance processes, structured as follows:

Response Example

http

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

[{
    "id": "25shTZfXmens1EYrgLBoTZpSgNKUXnLt",
    "status": "ISSUED",
    "group": "dnidemo",
    "data": [{
      "@context": ["https://www.w3.org/2018/credentials/v1"],
      "id": "cred:gatc:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "type": [
        "VerifiableCredential",
        "vIdCredential"
      ],
      "issuer": "did:gatc:acYseLtTEVeqF8...77uCKqyM3imEJH",
      "issuanceDate": "2018-06-21T17:05:23Z",
      "validFrom": "2018-06-21T17:05:23Z",
      "credentialSubject": {
        "id": "did:gatc:M2VhNjU2MzI...kOTdiNWMzZGI1",
        "documentType": "Passport",
        "firstName": "Luke",
        "lastName": "Skywalker",
        "identifier": "XXXXXXXXX",
        "dateOfBirth": "25-05-1977"
      },
      "credentialStatus": {
        "id": "https://base-uri/api/v1/group/dnidemo/status",
        "type": "CredentialStatusList2020"
      },
      "credentialSchema": {
        "id": "https://base-uri/tsr/verifiableid1.json",
        "type": "JsonSchemaValidator2018"
      },
      "evidence": {
        "id": "https://base-uri/evidence/fsdakflasdjlfkas",
        "type": [
          "DocumentVerification",
          "PassportVerification"
        ],
        "verifier": "did:ebsi:32Zn2k5DJPG5oxiFyfVJvRcwikVFu1Pa",
        "subjectPresence": "Physical",
        "documentPresence": "Physical",
        "evidenceDocument": {
          "type": "Passport",
          "documentCode": "P",
          "documentNumber": "SPECI2014",
          "documentIssuingState": "NLD",
          "documentExpirationDate": "2031-06-25T15:06:07Z"
        }
      }
    }],
    "validator": {
      "id": "25shTZfXmens1EYrgLBoTZpSgNKUXnLt",
      "securityMechanisms": {
        "@context": [
          "https://www.w3.org/2018/credentials/v1"
        ],
        "proof": [],
        "type": [
          "VerifiablePresentation",
          "GatacaCredentialPresentation"
        ]
      },
      "verifiablePresentation": {
        "@context": [
          "https://www.w3.org/2018/credentials/v1"
        ],
        "proof": [{
          "created": "2020-10-09T08:12:46Z",
          "creator": "did:gatc:M2VhNjU2MzI3NT...WMzZGI1#keys-1",
          "proofPurpose": "authentication",
          "proofValue": "9tEN6NmIovJxk9v7gChoVy...HbckK8ZXh9tMrCQ",
          "type": "Ed25519Signature2018"
        }],
        "type": [
          "VerifiablePresentation",
          "GatacaCredentialPresentation"
        ],
        "verifiableCredential": [{
          "credentialSubject": {
            "email": "[e-mail]",
            "id": "did:gatc:M2VhNjU2...kOTdiNWMzZGI1"
          },
          "id": "cred:gatc:ZGU5NGQ4MzFi...TMzNWQwODky",
          "issuanceDate": "2020-10-07T10:15:03Z",
          "issuer": "did:gatc:acYseLtTEVeqF8...77uCKqyM3imEJH",
          "proof": [{
            "created": "2020-10-07T10:15:03Z",
            "creator": "did:gatc:24gsRbsURij3edo...hggrnR#keys-1",
            "proofPurpose": "authentication",
            "proofValue": "wpQJlNwZfHUNesE...2KpGt4ygTJfzdBA",
            "type": "Ed25519Signature2018"
          }],
          "type": [
            "VerifiableCredential",
            "emailCredential"
          ]
        }]
      }
    },
    "createdAt": "2020-10-09T08:12:29.134017Z",
    "updatedAt": "2020-10-09T08:24:54.53356Z"
  }
]

Each entry in the response is structured as follows:

1. Issuance Process Metadata:

   • Contains key details about the issuance process, including:

     • Identifier: A unique identifier for the process.

     • Type: The type of issuance process.

     • Dates: Relevant timestamps (e.g., creation and update times).

     • Status: The current status of the process, which can be:

       • PENDING: The session has been created, but no additional information is associated yet.

       • ISSUED: Verifiable Credentials (VCs) associated with the process have been issued and downloaded.

       • REJECTED: The issuance process has been rejected by the issuer.

2. Data:

   • This field contains the new Verifiable Credentials (VCs) issued by the Relying Party.

   • It is populated only when the issuance process status is updated to ISSUED.

3. Validator:

   • Includes all the information shared by the end user that was requested by the Relying Party for authentication into Studio.

---

Alternative - Attended issuance flow

In the previous section, we defined how to implement an unattended issuance flow, where the request and issuance processes are carried out synchronously, without requiring any manual intervention. However, there are use cases where manual validation is required, often due to legal or regulatory requirements.

For these scenarios, where an asynchronous process is necessary, this operation provides the required functionality to accommodate manual validations.

In order to allow the administrator responsible for validations to list all pending processes and proceed with the required validation steps efficiently, it is essential to utilize this endpoint, which will provide all issuance requests:

Request Example

http

GET /admin/v1/issuanceRequests
Host: certify.gataca.io
Authorization: jwt [ACCESS-TOKEN]
Content-Type: application/json

• ACCESS-TOKEN: Access token received from the authentication call.

Moreover, the same endpoint supports query parameters, enabling filtering of issuance processes by specific statuses. This functionality streamlines searches and improves efficiency, allowing administrators to quickly locate and retrieve only the processes relevant to their validation tasks:

Request Example

http

GET /admin/v1/issuanceRequests?status=ISSUED
Host: certify.gataca.io
Authorization: jwt [ACCESS-TOKEN]
Content-Type: application/json

The response is an array of issuance processes with the following structure:

Response Example

http

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

[
  {
    "id": "25shTZfXmens1EYrgLBoTZpSgNKUXnLt",
    "status": "ISSUED",
    "group": "dnidemo",
    "data": [{
        "credentialStatus": {
          "id": "https://certify.gataca.io:9090/api/v1/group/dnidemo/status",
          "type": "CredentialStatusList2017"
        },
        "credentialSubject": {
          "firstName": "Samuel",
          "id": "did:gatc:M2VhNjU2MzI...kOTdiNWMzZGI1"
        },
        "id": "cred:gatc:g6hn7m...nvd4ukr61j43d",
        "issuer": "did:gatc:32Zn2...yfVJvRcwikVFu1Pa",
        "type": [
          "VerifiableCredential",
          "firstNameCredential"
        ]
      }
    ],
    "validator": {
      "id": "25shTZfXmens1EYrgLBoTZpSgNKUXnLt",
      "securityMechanisms": {
        "@context": [
          "https://www.w3.org/2018/credentials/v1"
        ],
        "proof": [],
        "type": [
          "VerifiablePresentation",
          "GatacaCredentialPresentation"
        ]
      },
      "verifiablePresentation": {
        "@context": [
          "https://www.w3.org/2018/credentials/v1"
        ],
        "proof": [{
          "created": "2020-10-09T08:12:46Z",
          "creator": "did:gatc:M2VhNjU2MzI3NT...WMzZGI1#keys-1",
          "proofPurpose": "authentication",
          "proofValue": "9tEN6NmIovJxk9v7gChoVy...HbckK8ZXh9tMrCQ",
          "type": "Ed25519Signature2018"
        }],
        "type": [
          "VerifiablePresentation",
          "GatacaCredentialPresentation"
        ],
        "verifiableCredential": [{
          "credentialSubject": {
            "email": "[e-mail]",
            "id": "did:gatc:M2VhNjU2...kOTdiNWMzZGI1"
          },
          "id": "cred:gatc:ZGU5NGQ4MzFi...TMzNWQwODky",
          "issuanceDate": "2020-10-07T10:15:03Z",
          "issuer": "did:gatc:acYseLtTEVeqF8...77uCKqyM3imEJH",
          "proof": [{
            "created": "2020-10-07T10:15:03Z",
            "creator": "did:gatc:24gsRbsURij3edo...hggrnR#keys-1",
            "proofPurpose": "authentication",
            "proofValue": "wpQJlNwZfHUNesE...2KpGt4ygTJfzdBA",
            "type": "Ed25519Signature2018"
          }],
          "type": [
            "VerifiableCredential",
            "emailCredential"
          ]
        }]
      }
    },
    "createdAt": "2020-10-09T08:12:29.134017Z",
    "updatedAt": "2020-10-09T08:24:54.53356Z"
  }
]

Information Structure

The response includes the following key components:

1. Issuance Process Metadata

• Identifier: Unique identifier for the issuance process.

• Type: Type of issuance process.

• Dates: Timestamps related to the creation and updates of the process.

• Status: Current status of the issuance process.

1. Status Definitions

• PENDING: The session has been created, but no information is currently associated with the process.

• ISSUED: Verifiable Credentials (VCs) associated with the issuance process have been successfully downloaded.

• REJECTED: The issuance process has been rejected by the issuer.

1. Data

• This field contains the newly issued Verifiable Credentials provided by the relying party.

• This field is populated only when the issuance process reaches an ISSUED status.

1. Validator

• This field includes all the information shared by the end user and requested by the relying party to authenticate into Studio.

This structure provides a comprehensive overview of the issuance process, ensuring clarity and accessibility for administrators handling these processes.

---

Integrating the GatacaQR Component for Identity Wallet Interaction

To streamline the interaction with identity wallets, Gataca offers the GatacaQR component, a versatile JavaScript library designed for seamless session management. This component simplifies the integration process for relying parties, enabling them to generate and manage sessions effortlessly while enhancing user experience.

Key Features of GatacaQR

• QR Code Rendering: Displays a QR code that users can scan to initiate interactions with their identity wallet.

• Real-Time Communication: Supports features such as polling and WebSocket integration for efficient session updates.

• Deep Link Triggering: Allows for direct interaction with mobile devices via deep links, bypassing the need for QR scanning in certain use cases.

• Customizable Layout: Offers flexibility to adapt the appearance of the QR code and its surrounding elements to align with the relying party’s branding and design preferences.

• Ease of Integration: Simplifies complex session management workflows, providing a user-friendly API for developers.

Getting Started with GatacaQR

Developers can access comprehensive manuals and resources for using the GatacaQR component through the following repositories:

• NPM: @gataca/qr
• GitHub: Gataca-QR Repository

By leveraging GatacaQR, developers can focus on building intuitive user journeys while relying on a robust, pre-built solution for wallet interactions. This component ensures a streamlined, secure, and highly adaptable way to integrate identity wallet capabilities into your application.

---

WebHooks

The Gataca Studio platform introduces support for web-hooks, providing users with a flexible mechanism to receive real-time notifications about specific events within the system. Web-hooks can be configured directly through the graphical user interface (GUI), enabling seamless integration with external systems or workflows.

How Web-Hooks Work

1. Configuration: Users will define web-hooks via the Studio interface, specifying the target endpoint (URL). This functionality will be available for each of the templates that define the issuance and verification processes.

2. Triggering Events: When an event of interest occurs, Studio sends an HTTP POST request to the user-defined endpoint.

3. Payload: The POST request contains a structured payload with relevant data about the event. This allows external systems to process the information immediately and take appropriate actions.

Webhook Payload Structure

The payload sent to the configured endpoint will follow this format:

{
  "id": "017c9ece-6869-417a-8550-3f8ceee23199",
  "subject": "did:gatc:000000...000000",
  "status": "SUCCESS",
  "payload": {
    "email": "[e-mail]",
    ...
  },
  "verificationResult":{
      "checks":[
         "matchingIds",
         "presentationProof",
         "securityMechanisms",
         "credentialProof"
      ],
      "warnings":[
         "urn:uuid:YjQzNWI4ODI1NWQ4ZTY2YjI5MGE4NzU5 credential status not available."
      ],
      "errors":[]
   }
}

• id: Process identifier

• subject: Subject identifier

• status: Whole process status (SUCCESS, REJECT)

• payload: [OPTIONAL] Map with the claims shared by the subject (avoid including id). If there is no info into the credential subject this field won’t be included.

• verificationResult: List of results (steps passed, warnings and errors)

Benefits of Web-hook Integration

• Real-Time Updates: Enables immediate processing of events by external systems.

• Custom Workflows: Allows users to automate responses or actions based on Studio events.

• Scalability: Supports integration with diverse applications, including CRMs, analytics platforms, or custom systems.