How to create a Web Integration Token

Product: Digital Identity Verification

After creating a Web Flow, you will need a Web Integration Token to generate the URL that your user will use to perform identity validations.

Please note that you must generate a different token for each of your users, and that you must generate a different token for each identity validation process that your user will perform.

In order to ease the process, Truora provides a Postman collection online:

https://www.postman.com/truora-api-docs/workspace/truora-api-docs/folder/26510995-9fc50159-1f32-43d2-80aa-2d69bf637b4f

Below, you will find the steps to generate the Web Integration Token for the URL that you will provide to your users.

Generate Integration Token

  1. Create a POST request with the next URL: https://api.account.truora.com/v1/api-keys. You can also refer to our API Reference.

  2. Add the next headers

    • Truora-API-Key: <truora api key> Get a Truora API key
    • Content-Type: application/x-www-form-urlencoded

  3. Add the following params in the request body with their respective values

    • key_type: web
    • grant: digital-identity
    • api_key_version: 1
    • country: The country where the validation is to be performed. Allowed: ALL.
    • redirect_url: URL where the user is to be redirected once the validation is completed.
    • flow_id: From flow creation.
    • account_id: Account ID linked with this validation. Use this ID to trace the validations performed by the account later on. Note that only Account IDs following the regex pattern [a-zA-Z0-9_.-]+ are supported. Please go to Create an Account ID to learn more about it.
    • phone (optional): If your validation flow contains a phone verification step, you can provide the user’s phone number if you have one*. Otherwise, the phone number will be provided by the user when doing the validation process. The format is + country_code phone_number e.g.: +570000000000.
    • emails (optional): If your validation flow contains an email verification step, you can provide the user’s email if you have one*. Otherwise, the email will be provided by the user when doing the validation process.

Note:

  • *If you take the option to set it yourself, the user will not be able to modify the phone number or the email, and the OTP code will arrive only to the phone number or email, provided by you.
  • If you wish to include additional information in the identity validation process, you can do so by registering the inputs using the following structure start_variables.metadata., followed by the variable name and its corresponding result. Example: start_variables.metadata.name = juan.
  1. Send the request and copy the api_key field generated by the response, as you will need it in subsequent steps.
POST
https://api.account.truora.com/v1/api-keys 

{
    "api_key": "eyJhbGc....",
    "message": "API key created successfully"
}

Build Process URL

To generate the URL, you’ll need the api_key field generated in the Generate Integration Token section.

sample image

Note: The Web Integration Tokens have a 2 hours shelf life by default

Get Process Status

  1. The process_id is a unique identifier assigned to each <api key> created in Truora, and it appears at the end of the URL when the flow is started. It is important to keep track of this process_id, as it is required to check the status of the process in the endpoint shown in the next step. Additionally, the API key can be verified on the https://jwt.io/ website to obtain information about the process.
JWT 

HEADER
{
  "alg": "HS256",
  "typ": "JWT"
}

PAYLOAD
{
  "account_id": "ACCXXXXXXXXXX",
  "additional_data": "{\"country\":\"ALL\",\"flow_id\":\"IPFXXXXXXXXXXX\",
  \"redirect_url\":\"redirect_url",
  "client_id": "TCI3ca341c4d9676046f26d1f8bd042XXXX",
  "exp": 16642119XX,
  "grant": "digital-identity",
  "iat": 16642047XX,
  "iss": "iss_url",
  "jti": "bd54322c-b32d-420a-89a3-6372b9593XXX",
  "key_name": "xxx",
  "key_type": "web",
  "username": "xxx"
}
  1. The current state of the fetch process is to create a GET request using the next URL https://api.identity.truora.com/v1/processes/{{process_id}}/result.
GET
https://api.identity.truora.com/v1/processes/{{process_id}}/result 

{
    "process_id": "IDPXXXXXXXXXXX",
    "account_id": "ACCXXXXXXXXXX",
    "client_id": "TCIXXXXXXXXXXX",
    "flow_id": "IPFXXXXXXXXXX",
    "created_via": "web",
    "flow_version": 2,
    "country": "CO",
    "status": "success",
    "validations": [
        {
            "validation_id": "VLDXXXXXXXXX",
            "ip_address": "XXX.XX.XXX.XXX",
            "account_id": "ACCXXXXXXXXX",
            "type": "document-validation",
            "validation_status": "success",
            "creation_date": "2023-04-20T15:23:23.16025688Z",
            "details": {
                "background_check": {
                    "check_id": "CHKXXXXXXX",
                    "check_url": "https://api.checks.truora.com/v1/checks/CHKXXXXX"
                },
                "document_details": {
                    "birth_place": "xxxxxx",
                    "country": "CO",
                    "creation_date": "2023-04-20T15:23:23.089302125Z",
                    "date_of_birth": "1988-06-21T00:00:00Z",
                    "document_number": "xxxxxxxx",
                    "document_type": "national-id",
                    "expedition_place": "xxxxxxxx",
                    "gender": "xxxxxx",
                    "height": "1.75",
                    "issue_date": "2006-07-xxT00:00:00Z",
                    "last_name": "xxxx xxxxxxx",
                    "mime_type": "image/jpeg",
                    "name": "xxxxxxx xxxxx",
                    "national_registrar": "xxxxx xxxx xxxx",
                    "production_data": "xxxxxx-F-xxxxxxx-xxxxxx",
                    "rh": "O+",
                    "update_date": "2023-04-20T15:23:55.156336961Z"
                },
                "document_validations": {
                    "data_consistency": [
                        {
                            "validation_name": "Validation of date of birth",
                            "result": "valid",
                            "validation_type": "date-of-birth-validation",
                            "message": "The date of birth is valid",
                            "manually_reviewed": false,
                            "created_at": "2023-04-20T15:23:55.363068644Z"
                        },
                        {
                            "validation_name": "Validation of Document Number",
                            "result": "valid",
                            "validation_type": "document-number-validation",
                            "message": "The document has a valid document number or NUIP",
                            "manually_reviewed": false,
                            "created_at": "2023-04-20T15:23:55.363070657Z"
                        }
                    ],
                    "government_database": [
                        {
                            "validation_name": "Validation of Government Database - Registraduría",
                            "result": "valid",
                            "validation_type": "government-database-digital-validation-certificate-cedula",
                            "message": "Document is current and registered in main identity database",
                            "manually_reviewed": false,
                            "created_at": "2023-04-20T15:23:57.361281416Z"
                        }
                    ]
                }
            },
            ],
            "remaining_retries": 2,
            "front_image": "front_image_url",
            "reverse_image": "reverse_image_url"
        },
        {
            "validation_id": "VLDXXXXXXXX",
            "ip_address": "XXX.XX.XXX.XXX",
            "account_id": "ACCXXXXXXXX",
            "type": "face-recognition",
            "validation_status": "success",
            "threshold": 0.65,
            "creation_date": "2023-04-20T15:24:03.757501287Z",
            "details": {
                "face_recognition_validations": {
                    "similarity_status": "success",
                    "confidence_score": 0.9
                }
            },
            "identity_process_id": "IDPXXXXXXXX",
            "front_image": "front_image_url"
        },
    ],
    "creation_date": "2023-04-20T15:23:04.187201186Z",
    "update_date": "2023-04-20T15:24:49Z"
}

The process_status can either be success or failure at the end. In the meantime, it will be pending. Success occurs when the document validation was successful. Failure can occur due to an internal error, a timeout, or if the document validation is declined.

Note: Whenever a validation fails due to inconsistencies in the validation process,a declined reason to indicate the specific reason for the failure Here’s a list of declined reasons.