How to integrate Digital ID using Go APIs

This guide explains how to integrate Digital ID into your app, using GBG Go. Your product manages the provider selection process. Once the user selects a provider, GBG Go handles the user experience through a hosted UI for complex interactions.

Prerequisites

To integrate Digital ID, you need:

A secure backend to make API calls
A frontend website or mobile app
An encryption key pair, with the public key formatted as a JWKS

Prepare your public JWKS

The publicJwks field takes your public key as a JSON Web Key Set (JWKS). A JWKS is a JSON object with a keys array. Include a single public key in the array. If you supply more than one key, then GBG Go uses only the first one. Keep your private key on your side, because you use it to decrypt the encrypted results.

Include only the public key. Don’t include these private key components:

EC keys: d
RSA keys: d, p, q, dp, dq, and qi

The following examples show an RSA public JWKS and an EC public JWKS:

{
  "keys": [
    {
      "kty": "RSA",
      "e": "AQAB",
      "use": "enc",
      "kid": "your-key-id-here",
      "alg": "RSA-OAEP-256",
      "n": "<base64url-encoded modulus>"
    }
  ]
}

{
  "keys": [
    {
      "kty": "EC",
      "use": "enc",
      "crv": "P-384",
      "kid": "your-key-id-here",
      "x": "<base64url-encoded x coordinate>",
      "y": "<base64url-encoded y coordinate>",
      "alg": "ECDH-ES"
    }
  ]
}

Step 1: List applicable providers

Display a list of identity providers and prompt the user to select one. Display each provider using both the logo and name as shown below to comply with brand requirements.

LA Wallet
Provider ID: usa-louisiana-wallet

BankID Sweden
Provider ID: sweden-bankid

MitID
Provider ID: denmark-mitid

CA DMV Wallet
Provider ID: usa-california-dmv

SPID
Provider ID: italy-spid

For a full list of all GBG Go supported providers, refer to the Digital ID portal.

Step 2: Create a session

After the user selects an identity provider, follow these steps:

Authenticate with GBG Go API

Use your API credentials to authenticate with the GBG Go API and obtain an access token. For detailed instructions, refer to the Authentication guide.

Start a journey

Use the /journey/start endpoint to initiate a customer journey.Sample request payload:

JSON

{
  "resourceId": "c8ce398acdf00ef3bfc1f5891e515a5312783a9e687b49a6174cc4c6eb256839@5nfl7yy3",
  "context": {
    "subject": {
      "sessions": [
        {
          "auth": [
            {
              "id": "DigitalIdentity",
              "redirectUri": "gbg.com/en/",
              "scope": "sweden-bankid"
            }
          ]
        }
      ],
      "identity": {}
    }
  }
}

For more details on starting a journey, refer to the Start a journey guide.

Fetch journey state

After starting the journey, use the /journey/state endpoint to retrieve the current state of the journey. This provides you with a URI to redirect the user to the Digital ID provider’s hosted UI. The response includes a sessionId and a launchUrl field as shown in the example below:

JSON

    {
  "metaData": {
    "createdTime": "2025-10-16T10:09:39.586Z",
    "completedTime": null
  },
  "status": "InProgress",
  "data": {
    "context": {
      "process": {
        "flow": {
          "DigitalId_LaunchUrl": {
            "process": {
              "journey": {
                "name": "Journey Name",
                "id": "4720df7abf23d56be6e9bf93d8f60d214c478008f3d2ea4c7b4ed70caa5919c4",
                "version": "23zmzi4l",
                "startedAt": "2025-10-16T10:09:39.625Z"
              },
              "instance": {
                "id": "PiI6Ft6TqngR8LNW9gfy0cqu",
                "instanceId": "PRC-3a16de93-aa78-11f0-b356-f607f2d1caae"
              }
            },
            "subject": {
              "identity": {},
              "sessions": [
                {
                  "auth": [
                    {
                      "id": "DigitalIdentity",
                      "scope": "sweden-bankid",
                      "redirectUri": "gbg.com/en/"
                    }
                  ]
                }
              ]
            },
            "result": {
              "advice": {},
              "note": {
                "sessionId": "667b1fcb-9bc1-80aa-af59-369bf4316b7a",
                "launchUrl": "https://api.trinsic.id/api/session/launch?clientToken=2FRXHXzXv7FVbeVtU5VgseaW6FGLBveXVUQgqM7s5BLjXd8ZBuLD46mpDq9cNFmibWumhHxfNVTP5vjjQHaoQCFbvMBCdkPipPiFJygUT39jiMwQcCvJNefZLsoJaz2eoacyMCbfM7htyof76zhiQZCVygasuZtwZ1gHkT3iJM3fZAm2nxDvncNLtwZE7EV97TBTvcsbswbvE4fxGHanczVDoD5LZJgmKZpCwmtzEeGFYWBXKZpJEFuUSC9nwHPpuQSYKsbSFosq8CVbaRYhG4MdCKBNDcc5iYP7FXNQndBYEZ9M4KsXxrURDBVt2mhdbLypqxdPGCbkFT5J3H8z4oz6iTkJqhC&sessionId=667b1fcb-9bc1-80aa-af59-369bf4316b7a"
              },
              "status": "complete",
              "outcome": "Session Launched"
            }
          },
          "DigitalId_GetResults": {
            "process": {
              "journey": {
                "name": "Journey Name",
                "id": "4720df7abf23d56be6e9bf93d8f60d214c478008f3d2ea4c7b4ed70caa5919c4",
                "version": "23zmzi4l",
                "startedAt": "2025-10-16T10:09:39.625Z"
              },
              "instance": {
                "id": "PiI6Ft6TqngR8LNW9gfy0cqu",
                "instanceId": "PRC-3a16de93-aa78-11f0-b356-f607f2d1caae"
              }
            },
            "subject": {
              "identity": {},
              "sessions": [
                {
                  "auth": [
                    {
                      "id": "DigitalIdentity",
                      "scope": "sweden-bankid",
                      "redirectUri": "gbg.com/en/"
                    }
                  ]
                }
              ]
            },
            "result": {
              "status": "pending",
              "advice": {}
            }
          }
        },
        "journey": {
          "name": "Journey Name",
          "id": "4720df7abf23d56be6e9bf93d8f60d214c478008f3d2ea4c7b4ed70caa5919c4",
          "version": "23zmzi4l",
          "startedAt": "2025-10-16T10:09:39.625Z"
        },
        "instance": {
          "id": "PiI6Ft6TqngR8LNW9gfy0cqu",
          "instanceId": "PRC-3a16de93-aa78-11f0-b356-f607f2d1caae"
        }
      },
      "subject": {
        "identity": {},
        "sessions": [
          {
            "auth": [
              {
                "id": "DigitalIdentity",
                "scope": "sweden-bankid",
                "redirectUri": "gbg.com/en/"
              }
            ]
          }
        ]
      },
      "result": {
        "status": "pending",
        "error": []
      }
    }
  },
  "instanceId": "PiI6Ft6TqngR8LNW9gfy0cqu"
}

Save the sessionId in your database and send the launchUrl to your frontend.

For more details on fetching the journey state, refer to the Fetch journey state guide.

Step 3: Launch session on frontend

When your frontend receives the launchUrl from your backend, launch it by navigating the user’s browser to the URL. This can be:

A top-level navigation
A new tab or window
A dialog

Step 4: Capture user redirect

When the user completes the session, they are redirected to your specified redirectUrl with added query parameters:

sessionId

Send the sessionId to your backend to fetch the final session results.

Step 5: Retrieve session results

After your frontend sends the sessionId to your backend, follow these steps:

Retrieve tasks

Use the /journey/tasks/list endpoint to get a list of tasks associated with the session. This helps you identify the specific task ID needed to fetch detailed results.

Submit task data

Use the /journey/task/update endpoint to submit any required data for the task.Sample request payload:

JSON

 {
  "intent": "Complete",
  "instanceId": "{{instanceId}}",
  "taskId": "{{taskId}}",
  "data": {
    "context": {
      "subject": {
        "sessions": [
          {
            "auth": [
              {
                "id": "DigitalIdentityResult",
                "clientId": "667b1fcb-9bc1-80aa-af59-369bf4316b7a"
              }
            ]
          }
        ],
        "identity": {}
      }
    }
  }
}

Submit the sessionId as clientId.For more details on submitting task data, refer to the Submit task data guide.

Fetch journey state

Use the /journey/state endpoint to check the status of the journey and retrieve the results.Sample request payload:

JSON

{
    "instanceId": "PiIbYsgiHp4R8JPz2vU5Y9l4"
}

The response includes the results of the Digital ID verification.sample response payload:

JSON

{
  "metaData": {
    "createdTime": "2025-10-16T10:16:55.059Z",
    "completedTime": "2025-10-16T10:18:42.201Z"
  },
  "status": "Completed",
  "data": {
    "context": {
      "process": {
        "flow": {
          "DigitalId_LaunchUrl": {
            "process": {
              "journey": {
                "name": "Journey Name",
                "id": "4720df7abf23d56be6e9bf93d8f60d214c478008f3d2ea4c7b4ed70caa5919c4",
                "version": "23zmzi4l",
                "startedAt": "2025-10-16T10:16:55.094Z"
              },
              "instance": {
                "id": "PiI9psZFqnkR8KlQLnYlDE0Z",
                "instanceId": "PRC-3da6c645-aa79-11f0-a950-2e76250c4d19"
              }
            },
            "subject": {
              "identity": {},
              "sessions": [
                {
                  "auth": [
                    {
                      "id": "DigitalIdentity",
                      "scope": "trinsic-test-sub-providers",
                      "redirectUri": "gbg.com/en/"
                    }
                  ]
                }
              ]
            },
            "result": {
              "advice": {},
              "note": {
                "sessionId": "667b2174-5dc1-80c0-9298-a8a226144b15",
                "launchUrl": "https://api.trinsic.id/api/session/launch?clientToken=2RPzQxmroZNXJUg4yiHxbepnjSLmgmvQeWiw6V1jEa9hRF5dqW4k8YVizi9kEk4uaasrg6gtoE9VbKZnGTtnqwtAE85ezAMpDdU5wEouVL9mmouVR12g58FqxrwaHtN3PF7KpEXxusyvMfSE45vADoPM3hq3LWLy23yM2Jjwbp93RaoYx6XvxEw9McoTZfMvv1hhKe3buWKGZcBDWfhSBKpPu2MaYRSQXXgWbejG2ADfjKMgB1oGP1KEwRx39XHRTHQ7Db8od5CHqrGdeTKPsWHdnPDN3pYNmcpJH8qmu9tGSKJSetXEydbZymvW4c2quRFWjVjkgaue7M7hNCn86Dn7fs37wux&sessionId=667b2174-5dc1-80c0-9298-a8a226144b15"
              },
              "status": "complete",
              "outcome": "Session Launched"
            }
          },
          "DigitalId_GetResults": {
            "process": {
              "journey": {
                "name": "Journey Name",
                "id": "4720df7abf23d56be6e9bf93d8f60d214c478008f3d2ea4c7b4ed70caa5919c4",
                "version": "23zmzi4l",
                "startedAt": "2025-10-16T10:16:55.094Z"
              },
              "instance": {
                "id": "PiI9psZFqnkR8KlQLnYlDE0Z",
                "instanceId": "PRC-3da6c645-aa79-11f0-a950-2e76250c4d19"
              }
            },
            "subject": {
              "identity": {},
              "sessions": [
                {
                  "auth": [
                    {
                      "id": "DigitalIdentityResult",
                      "clientId": "667b2174-5dc1-80c0-9298-a8a226144b15"
                    }
                  ]
                }
              ]
            },
            "result": {
              "advice": {
                "providerID": "trinsic-test-sub-providers",
                "subProviderID": "sub-provider-a",
                "status": "Successful"
              },
              "status": "complete",
              "note": {
                "subject": {
                  "identity": {
                    "firstName": "John",
                    "middleNames": [
                      "Jacob"
                    ],
                    "lastNames": [
                      "Doe"
                    ],
                    "dateOfBirth": "1990-06-30",
                    "currentAddress": {
                      "lines": [
                        "123 Street",
                        "Apt 1",
                        "Floor 2"
                      ],
                      "locality": "New York",
                      "administrativeArea": "NY",
                      "postalCode": "10001",
                      "country": "US"
                    }
                  }
                }
              },
              "subject": {
                "identity": {
                  "firstName": "John",
                  "middleNames": [
                    "Jacob"
                  ],
                  "lastNames": [
                    "Doe"
                  ],
                  "dateOfBirth": "1990-06-30",
                  "currentAddress": {
                    "lines": [
                      "123 Street",
                      "Apt 1",
                      "Floor 2"
                    ],
                    "locality": "New York",
                    "administrativeArea": "NY",
                    "postalCode": "10001",
                    "country": "US"
                  }
                }
              },
              "outcome": "Verified"
            }
          },
          "mgqen03sjzx4cpuelxn": {
            "process": {
              "instance": {
                "id": "PiI9psZFqnkR8KlQLnYlDE0Z",
                "instanceId": "PRC-3da6c645-aa79-11f0-a950-2e76250c4d19"
              },
              "journey": {
                "name": "Journey Name",
                "id": "4720df7abf23d56be6e9bf93d8f60d214c478008f3d2ea4c7b4ed70caa5919c4",
                "version": "23zmzi4l",
                "startedAt": "2025-10-16T10:16:55.094Z",
                "endedAt": "2025-10-16T10:18:41.958Z",
                "durationMilliSec": 106864
              }
            },
            "_ggo": {
              "evaluationStepInput": {
                "context.process.flow.DigitalId_LaunchUrl.result.outcome": "PASS",
                "context.process.flow.DigitalId_GetResults.result.outcome": "Verified"
              }
            },
            "result": {
              "outcome": "Decision: Accept"
            }
          }
        },
        "journey": {
          "name": "Journey Name",
          "id": "4720df7abf23d56be6e9bf93d8f60d214c478008f3d2ea4c7b4ed70caa5919c4",
          "version": "23zmzi4l",
          "startedAt": "2025-10-16T10:16:55.094Z",
          "endedAt": "2025-10-16T10:18:41.958Z",
          "durationMilliSec": 106864
        },
        "instance": {
          "id": "PiI9psZFqnkR8KlQLnYlDE0Z",
          "instanceId": "PRC-3da6c645-aa79-11f0-a950-2e76250c4d19"
        }
      },
      "subject": {
        "identity": {},
        "sessions": [
          {
            "auth": [
              {
                "id": "DigitalIdentity",
                "scope": "trinsic-test-sub-providers",
                "redirectUri": "gbg.com/en/"
              }
            ]
          }
        ]
      },
      "result": {
        "status": "complete",
        "error": []
      }
    }
  },
  "instanceId": "PiI9psZFqnkR8KlQLnYlDE0Z"
}

For more details on fetching the journey state, refer to the Fetch journey state guide.

Troubleshooting

This section covers errors you might see when you send your public JWKS.

Invalid value format for `publicJwks`

If the publicJwks value isn’t in the expected format, then the API returns this error:

JSON

{
  "errors": [
    {
      "code": 4003,
      "location": "Body",
      "problem": "Invalid value format provided for the field 'publicJwks'",
      "action": "Please supply a value for this field in the correct format"
    }
  ]
}

To fix the error:

Check that the value is a JWKS object with a keys array. A single JSON Web Key (JWK) or a PEM string isn’t valid.
Check that the key contains only public components.
Validate the JSON. Look for trailing commas and incorrect quoting.
Send the request again.

Get Started

Platform

Developer Integration

Digital IDs

Resources

How to integrate Digital ID using Go APIs

Prerequisites

Prepare your public JWKS

Step 1: List applicable providers

Step 2: Create a session

Step 3: Launch session on frontend

Step 4: Capture user redirect

Step 5: Retrieve session results

Troubleshooting

Invalid value format for `publicJwks`

​Prerequisites

​Prepare your public JWKS

​Step 1: List applicable providers

​Step 2: Create a session

​Step 3: Launch session on frontend

​Step 4: Capture user redirect

​Step 5: Retrieve session results

​Troubleshooting

​Invalid value format for publicJwks

Prerequisites

Prepare your public JWKS

Step 1: List applicable providers

Step 2: Create a session

Step 3: Launch session on frontend

Step 4: Capture user redirect

Step 5: Retrieve session results

Troubleshooting

Invalid value format for `publicJwks`