SSI Verification Integration
Introduction
Objective
This document explains how to integrate Gataca’s SSI Credential Verification Service into your infrastructure. The integration enables your system to verify Verifiable Credentials (VCs) in compliance with W3C DID and Verifiable Credentials standards.
Target Audience
Developers, solution architects, and system administrators responsible for integration.
Key Benefits
Verify interoperable Verifiable Credentials seamlessly.
Ensure compliance with international SSI standards for trusted verification.
Enhance trust by confirming data authenticity and integrity.
Enable decentralized and privacy-preserving credential verification.
Streamline user experiences with fast and secure verification processes.
Prerequisites
Internet access to consume the exposed APIs over HTTPS.
Ports: 443 (TLS/SSL).
Integration Workflow
The following steps outline the workflow for credential verification:
The client sends a credential verification request to the API.
The API validates the request and processes the data.
The backend verifier verifies the data exchanged.
Sequence Diagram
The diagram below illustrates the SSI authentication flow. This documentation will only focus on the steps relevant to the integration process.
API Endpoints
Detailed API endpoint documentation (including request/response formats, parameters, and error codes) is provided in the Swagger documentation.
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 Verification Template if required. Once the API key is successfully generated, click the Save button to confirm the configuration.
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.
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
POST /admin/v1/api_keys/login
Host: nucleus.gataca.io
Authorization: Basic [API-KEY-CREDENTIALS]
tenant: [TENANT]
ssiconfig: [TEMPLATE-ID]
Content-Type: application/jsonAPI-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/1.1 200 OK
Content-Type: application/json
Token: ACCESS-TOKEN
Token_type: jwt
{
"message": "SUCCESS"
}Verifying Credentials
To verify a Verifiable Credential and ensure its association with a subject, the credential’s authenticity and integrity must first be confirmed. This requires a verification process, where the credential is validated against its associated DID (Decentralized Identifier) and checked for compliance with cryptographic proofs.
Once the credential and its associated data are successfully validated, the verifier can trust the information it contains and proceed to grant access or perform the required action based on the verified details.
4. Generating Verification Process instance
Request Example
POST /api/v3/sessions
Host: connect.gataca.io
Authorization: jwt [ACCESS-TOKEN]
Content-Type: application/json
{
"ssiConfigId":"VERIFICATION-TEMPLATE-ID"
}ACCESS-TOKEN: Access token received from the authentication request (This authentication must be executed by an application linked to the tenant selected into the authentication request).VERIFICATION-TEMPLATE-ID: This is the Verification Template Identifier you gave in the configuration settings when creating your verification template in Gataca Studio.
Response Example
HTTP/1.1 201 OK
Content-Type: application/json
{
"authentication_request":"openid-vp://?client_id=https%3A%2F%2Fconnect.gataca.io%2Fapi%2Fv3%2Ftenants%2F29KKv46fz3kZ5jvxjBqtAq9RvqJwoA2X%2Foidc-verifier%2FTest\u0026redirect_uri=https%3A%2F%2Fconnect.gataca.io%2Fapi%2Fv3%2Ftenants%2F29KKv46fz3kZ5jvxjBqtAq9RvqJwoA2X%2Foidc-verifier%2FTest%2Fauthorization-responses%2F4m8TLXcRUDpMrXkzorhoTpwMu6pkw4pUtHVSBf422c98\u0026request_uri=https%3A%2F%2Fconnect.gataca.io%2Fapi%2Fv3%2Ftenants%2F29KKv46fz3kZ5jvxjBqtAq9RvqJwoA2X%2Foidc-verifier%2FTest%2Frequest%2F4m8TLXcRUDpMrXkzorhoTpwMu6pkw4pUtHVSBf422c98\u0026response_mode=direct_post\u0026response_type=vp_token\u0026scope=openid",
"presentation_definition":{
"dataAgreement":{
"@context":"https://schema.igrant.io/data-agreements/v1",
"data_receiver":{
"id":"did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv",
"consent_duration":365,
"form_of_consent":"explicit",
"url":"https://connect.gataca.io"
},
"event":[
{
"principle_did":"did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv",
"proof":[
{
"created":"2025-01-27T18:33:35Z",
"creator":"did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1",
"domain":"gataca.io",
"nonce":"OMHLoaLQ5YpcyrXg0tqAxWCD9vSlkED8MeaWyDN0Urw=",
"proofPurpose":"assertionMethod",
"signatureValue":"lo75h936wQw3Jok41N1C6jzrEt5Sb20KBQ8xdefG1UOuKHmX11cTJAHZzNSyXJHEy95pCIcTY2UMDcUuhGuyDQ",
"type":"JcsEd25519Signature2020",
"verificationMethod":"did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1"
}
],
"state":"Preparation",
"version":"0",
"timestamp":1738002815098
}
],
"id":"2obqpkUVGy367qdpnrdpkAdSzVodZz4bhcE32Bs5movF",
"personal_data":[
{
"attribute_name":"emailCredential",
"attribute_sensitive":true,
"purposes":[
""
]
}
],
"purposes":null,
"template_id":"Test",
"template_version":"1",
"version":"0"
},
"name":"Test",
"id":"4m8TLXcRUDpMrXkzorhoTpwMu6pkw4pUtHVSBf422c98",
"format":{
"jwt":{
"alg":[
"EdDSA",
"ES256",
"ES256K"
]
},
"jwt_vp":{
"alg":[
"EdDSA",
"ES256",
"ES256K"
]
},
"ldp":{
"proof_type":[
"JsonWebSignature2020",
"Ed25519Signature2018",
"EcdsaSecp256k1Signature2019",
"RsaSignature2018"
]
},
"ldp_vp":{
"proof_type":[
"JsonWebSignature2020",
"Ed25519Signature2018",
"EcdsaSecp256k1Signature2019",
"RsaSignature2018"
]
}
},
"submission_requirements":[
{
"name":"Mandatory data",
"purpose":"Basic data to provide the service",
"rule":"all",
"from":"mandatory"
},
{
"name":"Optional data",
"purpose":"Additional data to enrich the service",
"rule":"pick",
"min":0,
"from":"optional"
}
],
"input_descriptors":[
{
"id":"emailCredential",
"name":"emailCredential",
"group":[
"mandatory"
],
"constraints":{
"fields":[
{
"path":[
"$.type[-1:]",
"$.vc.type[-1:]"
],
"purpose":"The claim must be of a specific type",
"filter":{
"type":"string",
"pattern":"emailCredential"
},
"intent_to_retain":true
},
{
"path":[
"$.issuer",
"$.vc.issuer",
"$.iss"
],
"purpose":"Assert the trust of the issuer",
"filter":{
"type":"string",
"pattern":"(||||did:gatc:24gsRbsURij3edoveHv81jt9EnhggrnR|did:ebsi:zx23VjG43EsmTuTA3EvQQnd|did:ebsifnmt:zx262gXXXuRXxDfDdkf8oLG|did:gatc:24uATHrisWkLFnDMgRHcwQvzkjLB8tWE)"
}
}
],
"statuses":{
"active":{
"directive":"required"
}
}
}
}
],
"proof":[
{
"created":"2025-01-27T18:33:35Z",
"creator":"did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1",
"domain":"gataca.io",
"nonce":"GMAa84Mp_PdcyTN6ebNryHpRcNw970yrsoEBKlSPxY8=",
"proofPurpose":"authentication",
"signatureValue":"atQqJ4AMcpE0VBdHv7VAVdVwRMim2GTrGudt1rsERxIC5L57WCzDREHdL6mjQ8gEmYlZur9pKC48amxgPnaRDg",
"type":"JcsEd25519Signature2020",
"verificationMethod":"did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1"
}
]
}
}This response is too big to be displayed in a QR code, so only the authentication_request field is shown to represent the session in the QR code. This session identifier (id) is required for the following step, so make sure to copy it.
In the section requested are all the Verifiable Credentials requested by the Verifier, which all follow the same structure. In this example, it is requesting this VC type.
Email Name:
emailCredential
The structure of the Verifiable Credential shows the credential type (email), that the credential must be shared (it is mandatory), needs to be issued by a trusted issuer as the Trust Level is 1 (Validation), and the purpose for requesting the credential (authentication).
5. Validating the Issuance Process
Getting the information from a specific verification process is also possible using the command below. Instead of retrieving information from a set of verification processes, this command retrieves the information from a specific verification process (using the process identifier).
Request Example
GET /api/v3/sessions/[VERIFICATION-ID]
Host: connect.gataca.io
Authorization: jwt [ACCESS-TOKEN]
Content-Type: application/jsonVERIFICATION-ID: Session identifier. It must be recovered from the generated session response (Step 3). In this case,4m8TLXcRUDpMrXkzorhoTpwMu6pkw4pUtHVSBf422c98.ACCESS-TOKEN: Access token received from the authentication request (This authentication must be executed by an application linked to the tenant selected into the authentication request).
Response Example
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"Id": "AUFu7juZg2UgnUzaELCsWbhGQduMRzxzQaoww1aLzySN",
"PresentationSubmission": null,
"PresentationSubmissionFormat": "",
"Validations": null,
"PresentationDefinition": {
"dataAgreement": {
"@context": "https://schema.igrant.io/data-agreements/v1",
"data_receiver": {
"id": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv",
"consent_duration": 365,
"form_of_consent": "explicit",
"url": "https://connect.gataca.io"
},
"event": [
{
"principle_did": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv",
"proof": [
{
"created": "2025-01-27T19:16:20Z",
"creator": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1",
"domain": "gataca.io",
"nonce": "ZN4VE13taIj_D6IBswsZwQ3wgjLCJJA-bdGBuTRxl8U=",
"proofPurpose": "assertionMethod",
"signatureValue": "6daZkZ8R1udFWELu8XYr1uOXvHy3SYT19fkspmPFzL_thfTiwl8w9QedmtSHgIMYpe75HPkUUBQp6B992Z6oBg",
"type": "JcsEd25519Signature2020",
"verificationMethod": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1"
}
],
"state": "Preparation",
"version": "0",
"timestamp": 1738005380501
}
],
"id": "76DdAevHf8TrphxTvDfny78fDZjTRj1qX4xXW4LMLJcV",
"personal_data": [
{
"attribute_name": "emailCredential",
"attribute_sensitive": true,
"purposes": [
""
]
}
],
"purposes": null,
"template_id": "Test",
"template_version": "1",
"version": "0"
},
"name": "Test",
"id": "AUFu7juZg2UgnUzaELCsWbhGQduMRzxzQaoww1aLzySN",
"format": {
"jwt": {
"alg": [
"EdDSA",
"ES256",
"ES256K"
]
},
"jwt_vp": {
"alg": [
"EdDSA",
"ES256",
"ES256K"
]
},
"ldp": {
"proof_type": [
"JsonWebSignature2020",
"Ed25519Signature2018",
"EcdsaSecp256k1Signature2019",
"RsaSignature2018"
]
},
"ldp_vp": {
"proof_type": [
"JsonWebSignature2020",
"Ed25519Signature2018",
"EcdsaSecp256k1Signature2019",
"RsaSignature2018"
]
}
},
"submission_requirements": [
{
"name": "Mandatory data",
"purpose": "Basic data to provide the service",
"rule": "all",
"from": "mandatory"
},
{
"name": "Optional data",
"purpose": "Additional data to enrich the service",
"rule": "pick",
"min": 0,
"from": "optional"
}
],
"input_descriptors": [
{
"id": "emailCredential",
"name": "emailCredential",
"group": [
"mandatory"
],
"constraints": {
"fields": [
{
"path": [
"$.type[-1:]",
"$.vc.type[-1:]"
],
"purpose": "The claim must be of a specific type",
"filter": {
"type": "string",
"pattern": "emailCredential"
},
"intent_to_retain": true
},
{
"path": [
"$.issuer",
"$.vc.issuer",
"$.iss"
],
"purpose": "Assert the trust of the issuer",
"filter": {
"type": "string",
"pattern": "(||||did:gatc:24gsRbsURij3edoveHv81jt9EnhggrnR|did:ebsi:zx23VjG43EsmTuTA3EvQQnd|did:ebsifnmt:zx262gXXXuRXxDfDdkf8oLG|did:gatc:24uATHrisWkLFnDMgRHcwQvzkjLB8tWE)"
}
}
],
"statuses": {
"active": {
"directive": "required"
}
}
}
}
],
"proof": [
{
"created": "2025-01-27T19:16:20Z",
"creator": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1",
"domain": "gataca.io",
"nonce": "VuWnEXbC-KDZmVJECpayg4w7T6YKAB-pWGMujy_I3gY=",
"proofPurpose": "authentication",
"signatureValue": "X3K_QfJhMWykCcQJ1D6qbOGn0xlLdbv1GhyqYoTUJUW7bzS27vH8Unh2xMO4EflwEo_hr_fwpyXsNF7rvy5lBQ",
"type": "JcsEd25519Signature2020",
"verificationMethod": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1"
}
]
},
"AuthRequest": {
"exp": 1738005680,
"iss": "https://connect.gataca.io/api/v3/tenants/29KKv46fz3kZ5jvxjBqtAq9RvqJwoA2X/oidc-verifier/Test",
"response_type": "vp_token",
"client_id": "https://connect.gataca.io/api/v3/tenants/29KKv46fz3kZ5jvxjBqtAq9RvqJwoA2X/oidc-verifier/Test",
"redirect_uri": "https://connect.gataca.io/api/v3/tenants/29KKv46fz3kZ5jvxjBqtAq9RvqJwoA2X/oidc-verifier/Test/authorization-responses/AUFu7juZg2UgnUzaELCsWbhGQduMRzxzQaoww1aLzySN",
"state": "EMi5jHoYFqicZ7frDQbdkfFa1sBK5grcXKVYRVgSYzk8",
"scope": "openid",
"response_mode": "direct_post",
"nonce": "5GpefxLWz3BzLmR69b4wskqeYgE5ZZ21jAvgLXNZNAe4",
"presentation_definition": {
"dataAgreement": {
"@context": "https://schema.igrant.io/data-agreements/v1",
"data_receiver": {
"id": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv",
"consent_duration": 365,
"form_of_consent": "explicit",
"url": "https://connect.gataca.io"
},
"event": [
{
"principle_did": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv",
"proof": [
{
"created": "2025-01-27T19:16:20Z",
"creator": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1",
"domain": "gataca.io",
"nonce": "ZN4VE13taIj_D6IBswsZwQ3wgjLCJJA-bdGBuTRxl8U=",
"proofPurpose": "assertionMethod",
"signatureValue": "6daZkZ8R1udFWELu8XYr1uOXvHy3SYT19fkspmPFzL_thfTiwl8w9QedmtSHgIMYpe75HPkUUBQp6B992Z6oBg",
"type": "JcsEd25519Signature2020",
"verificationMethod": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1"
}
],
"state": "Preparation",
"version": "0",
"timestamp": 1738005380501
}
],
"id": "76DdAevHf8TrphxTvDfny78fDZjTRj1qX4xXW4LMLJcV",
"personal_data": [
{
"attribute_name": "emailCredential",
"attribute_sensitive": true,
"purposes": [
""
]
}
],
"purposes": null,
"template_id": "Test",
"template_version": "1",
"version": "0"
},
"name": "Test",
"id": "AUFu7juZg2UgnUzaELCsWbhGQduMRzxzQaoww1aLzySN",
"format": {
"jwt": {
"alg": [
"EdDSA",
"ES256",
"ES256K"
]
},
"jwt_vp": {
"alg": [
"EdDSA",
"ES256",
"ES256K"
]
},
"ldp": {
"proof_type": [
"JsonWebSignature2020",
"Ed25519Signature2018",
"EcdsaSecp256k1Signature2019",
"RsaSignature2018"
]
},
"ldp_vp": {
"proof_type": [
"JsonWebSignature2020",
"Ed25519Signature2018",
"EcdsaSecp256k1Signature2019",
"RsaSignature2018"
]
}
},
"submission_requirements": [
{
"name": "Mandatory data",
"purpose": "Basic data to provide the service",
"rule": "all",
"from": "mandatory"
},
{
"name": "Optional data",
"purpose": "Additional data to enrich the service",
"rule": "pick",
"min": 0,
"from": "optional"
}
],
"input_descriptors": [
{
"id": "emailCredential",
"name": "emailCredential",
"group": [
"mandatory"
],
"constraints": {
"fields": [
{
"path": [
"$.type[-1:]",
"$.vc.type[-1:]"
],
"purpose": "The claim must be of a specific type",
"filter": {
"type": "string",
"pattern": "emailCredential"
},
"intent_to_retain": true
},
{
"path": [
"$.issuer",
"$.vc.issuer",
"$.iss"
],
"purpose": "Assert the trust of the issuer",
"filter": {
"type": "string",
"pattern": "(||||did:gatc:24gsRbsURij3edoveHv81jt9EnhggrnR|did:ebsi:zx23VjG43EsmTuTA3EvQQnd|did:ebsifnmt:zx262gXXXuRXxDfDdkf8oLG|did:gatc:24uATHrisWkLFnDMgRHcwQvzkjLB8tWE)"
}
}
],
"statuses": {
"active": {
"directive": "required"
}
}
}
}
],
"proof": [
{
"created": "2025-01-27T19:16:20Z",
"creator": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1",
"domain": "gataca.io",
"nonce": "VuWnEXbC-KDZmVJECpayg4w7T6YKAB-pWGMujy_I3gY=",
"proofPurpose": "authentication",
"signatureValue": "X3K_QfJhMWykCcQJ1D6qbOGn0xlLdbv1GhyqYoTUJUW7bzS27vH8Unh2xMO4EflwEo_hr_fwpyXsNF7rvy5lBQ",
"type": "JcsEd25519Signature2020",
"verificationMethod": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1"
}
]
}
},
"RequestedAt": null,
"CreatedAt": "2025-01-27T19:16:20.504775Z",
"UpdatedAt": "2025-01-27T19:16:20.516899Z",
"ExpiredAt": "2025-01-27T19:21:20.504774Z",
"DeletedAt": null,
"SourceWallet": "",
"Callback": "",
"Subject": ""
}The field PresentationSubmission includes the information the user shares, which in this case is only the email.
With this information, the user has been authenticated, which is used to authorize or not the user in the client service.
If you have any questions or need assistance integrating Gataca Studio, please get in touch with our support team at [email protected] for further assistance.
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
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.
Triggering Events: When an event of interest occurs, Studio sends an HTTP POST request to the user-defined endpoint.
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": "[email protected]",
...
},
"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.
Last updated