Home

SSI Verification Integration

This documentation will guide you through the process of integrating Gataca Studio with your application for an authentication process, providing you with step-by-step instructions, code snippets, and other helpful resources.

The integration consists of several API calls, so we will guide you through the structure of the API endpoint and the data structure necessary to understand the request.

Sequence Diagram

The diagram below illustrates the SSI authentication flow. This documentation will only focus on the steps relevant to the integration process.

  • User Wallet: Gataca Wallet

  • 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.

  • Connect: Verifier component in Gataca Studio

Integration process

Authentication request

To start the integration process, you must have already created a verification template and an API Key in Gataca Studio.

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.

This access token will then be included in subsequent requests to the protected endpoint, allowing the user to bypass the authentication process for a certain period of time (until the token expires or is revoked).

To obtain the corresponding access token to use any of the protected endpoints, it is necessary to use the following API call in your application:

curl --request POST 'https://nucleus.gataca.io/admin/v1/api_keys/login' \
        --header 'Authorization: Basic [AUTH]'
        --header 'tenant: [TENANT_ID]'
        --header 'ssiconfig: [SSI_CONFIG_ID]'

  • AUTH: base64(apikey:password) - 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_ID: This is the identifier for each tenant (organization) into the Studio platform. This identifier can be get it in the following section.

  • SSI_CONFIG_ID: This identifier refers to the feature you are trying to perform. In case of Issuance / Verificaiton templates, the identifier will be template identifier.

The server then verifies these credentials and, if they are valid, issues an access token that you can use to access the protected endpoint.

The response of this endpoint is:

{
    "message": "SUCCESS"
}

  • Status code: 200. If the authentication is rejected, the status code will be 403.

The response also has the following headers attached:

  • Header.Token: Access token received to access the protected endpoints.

  • Header.Token_type: Type of token used by Gataca. By default, it is jwt (JSON Web Token).

  • set-cookie: Cookie with the access token related with the previous execution.

You will need the access token in the following steps, so make sure to copy it.

Generate a Session (Sequence Diagram Steps 2 - 3)

The token received in the previous step must be used to generate a new session (Step 2).

curl --request POST 'https://connect.gataca.io/api/v2/sessions' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: [APP_TOKEN_TYPE] [APP_TOKEN]' \
      --data-raw '{"ssiConfigId": "[TEMPLATE_ID]"}'

  • APP_TOKEN_TYPE: Type of token received from the authentication call. Currently, GATACA always uses jwt.

  • APP_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).

  • TEMPLATE_ID: This is the Verification Template Identifier you gave in the configuration settings when creating your verification template in Gataca Studio.

The response (Step 3) is:

{
    "auth": [
        {
            "accepted": [
                "biometric",
                "silent"
            ],
            "type": "AuthNFactor"
        }
    ],
    "callback": [CALLBACK_HOST],
    "id": "d2799966-c4fb-43ec-8883-90ef58e12945",
    "nonce": "d39ba63c-7e93-441f-aab2-7dc20da43e79",
    "proof": [
        {
            "challenge": "31DUpB9TEEbX2UMunDn77ABYkwZBrNHQ",
            "created": "2021-06-14T21:52:39Z",
            "creator": "did:gatc:21CqNkY...Ubawv9q#keys-1",
            "domain": "gataca.io",
            "proofPurpose": "authentication",
            "proofValue": "Puo3gx9s7v...PHc0mHzU9GQ5RDQ",
            "type": "Ed25519Signature2018",
            "verificationMethod": "did:gatc:21CqNkY...Ubawv9q#keys-1"
        }
    ],
    "requested": [
        {
            "mandatory": true,
            "purpose": "Authentication",
            "trustLevel": 1,
            "type": "emailCredential"
        },
        {
            "mandatory": false,
            "purpose": "Application Logic",
            "trustLevel": 0,
            "type": "deviceIdCredential"
        }
    ]
}

  • CALLBACK_HOST: URL the user wallet will use to share the information with Studio.

This response is too big to be displayed in a QR code, so only the ID is shown to represent the session in the QR code (In this case, d2799966-c4fb-43ec-8883-90ef58e12945). This session identifier 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 two different VC types.

  • Email Name: emailCredential

  • Device ID: deviceIdCredential

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).

In the second example, the device id is optional, meaning the user can refuse to share it. The Trust level is 0, so it could be issued by any issuer or self-attested by the user in the business logic.

The response also has the following attached:

  • Header.Token: Access token received to check if the session is satisfactory. This token works with this specific session.

  • Header.Token_type: Type of token used by Gataca. By default, it is jwt.

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.

Get Session Info (Sequence Diagram Steps 4 & 15 - 5 & 16)

This function (Steps 4 & 15) checks whether the session has been filled.

curl --request GET 'https://connect.gataca.io/api/v2/sessions/[SESSION_ID]' \
        --header 'Authorization: [TOKEN_TYPE] [CREATION_TOKEN]'

  • SESSION_ID: Session identifier. It must be recovered from the generated session response (Step 3). In this case, d2799966-c4fb-43ec-8883-90ef58e12945.

  • TOKEN_TYPE: Type of token received from the session generation process (previous step). Currently, GATACA always uses jwt.

  • CREATION_TOKEN: Token received from the session generation process (previous step).

The response (steps 5 & 16) is:

  • Empty if the status is 204. It means the session has not been filled yet.

  • Empty if the status is 403. It means the token used is incorrect (expired/wrong)

  • If the status code is 200, the endpoint returns the following payload. It means the user has been authenticated correctly.

{
  "auth": [{
    "accepted": [
      "biometric",
      "silent"
    ],
    "type": "AuthNFactor"
  }],
  "callback": [CALLBACK_HOST],
  "id": "d2799966-c4fb-43ec-8883-90ef58e12945",
  "nonce": "d39ba63c-7e93-441f-aab2-7dc20da43e79",
  "proof": [{
    "challenge": "31DUpB9TEEbX2UMunDn77ABYkwZBrNHQ",
    "created": "2021-06-14T21:52:39Z",
    "creator": "did:gatc:21CqNkY...Ubawv9q#keys-1",
    "domain": "gataca.io",
    "proofPurpose": "authentication",
    "proofValue": "Puo3gx9s7v...PHc0mHzU9GQ5RDQ",
    "type": "Ed25519Signature2018",
    "verificationMethod": "did:gatc:21CqNkY...Ubawv9q#keys-1"
  }],
  "requested": [{
      "mandatory": true,
      "purpose": "Authentication",
      "trustLevel": 1,
      "type": "emailCredential"
    },
    {
      "mandatory": false,
      "purpose": "Application Logic",
      "trustLevel": 0,
      "type": "deviceIdCredential"
    }
  ],
  "data": {
    "@context": ["https://www.w3.org/2018/credentials/v1"],
    "proof": [{
      "created": "2020-11-18T17:10:29Z",
      "creator": "did:gatc:Y2VmMjczNzR...mMDE4#keys-1",
      "proofPurpose": "authentication",
      "proofValue": "PZ1aGMMP6...QlfXVQC-uBXgZDg",
      "type": "Ed25519Signature2018"
    }],
    "type": ["VerifiablePresentation", "GatacaCredentialPresentation"],
    "verifiableCredential": [{
      "credentialSubject": {
        "email": "test@gataca.io",
        "id": "did:gatc:NDUyZGViZ...IwMzgyMzY2"
      },
      "id": "cred:gatc:ODk1MTZjMjU3YmIyN2E3ZGU0YjhmMTJj",
      "issuanceDate": "2020-11-18T12:53:19Z",
      "issuer": "did:gatc:acYseLtTEVeqF8...Xjcc77uCKqyM3imEJH",
      "proof": [{
        "created": "2020-11-18T12:53:21Z",
        "creator": "did:gatc:24gsRbs...ggrnR#keys-1",
        "proofPurpose": "authentication",
        "proofValue": "yedkgvsu...nloapuNEx5Dw",
        "type": "Ed25519Signature2018"
      }],
      "type": ["VerifiableCredential", "emailCredential"]
    }]
  }
}

  • CALLBACK_HOST: URL where the wallet must send the response.

The field data is 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 your service.

If you have any questions or need assistance integrating Gataca Studio, please get in touch with our support team at help@gataca.io for further assistance.

GatacaQR component

Instead of manually doing the previous process, you can also use GatacaQR. This JavaScript component implements a set of features to allow any relying party to execute the session generation in a simple way.

These repositories contain developer manuals on using the GatacaQR component:

GitHub: GitHub - gataca-io/gataca-QR

API Documentation with Swagger

PreviousSSI Issuance IntegrationNextGataca Vouch Integration

Last updated