Using Aliases for Flexible User Identification

In today’s digital landscape, users often have multiple identifiers - an email address, a phone number, or a username. Truora’s Alias service addresses this complexity by providing a flexible way to manage these multiple identifiers efficiently across our services.

Why Use Aliases?

Aliases allow you to associate multiple identifiers with a single validated account, offering several key benefits:

1. Users can interact with your system using their preferred identifier, enhancing convenience and satisfaction.
2. By linking all identifiers to a single validated account, you maintain the integrity of your identity verification process.
3. If a user’s primary identifier changes, updating the alias is simpler than changing the account_id across all services. While the account_id cannot be changed, multiple aliases can be added without restriction.

When to Use Aliases

Aliases are particularly useful in scenarios such as:

1. User registration and login systems.
2. Account recovery processes.
3. Systems requiring multiple forms of user identification.

By effectively incorporating aliases into your use of Truora services, you can create a more user-friendly and adaptable identity verification system for your end-users.

Prerequisites

Before creating an alias, ensure that:

1. You have created an account for the user. Please visit Create an Account ID to learn more about it.

2. The account has successfully completed the validation process.

3. You have the account_id of the validated account.
   
   

   Visit our Validators Guides to learn more about creating and performing a validation for each case:

   • Document Validation via API.
   • Face Validation via API.
   • Phone Validation via API.
   • Email Validation via API.
   • TruFace Validation.

Create alias

Setup main Request Headers and Body

To configure the main request headers and body, follow these steps:

1. Create a POST request to the endpoint https://api.validations.truora.com/v1/aliases

2. Set the Headers

   • Truora-API-Key: enter the value of your Truora API-key, the same used during the validation process.
   • Content-Type: the value should be application/x-www-form-urlencoded.

3. Set required values for the request body:

• alias_id [Required]: A unique identifier for the alias. This can be any string that follows the regex pattern [a-zA-Z0-9_.@-]+. Examples include email addresses, phone numbers, or any custom identifier.
• account_id [Required]: The account ID that this alias will be associated with. This should be an existing account ID of a validated account in the system.

For the purposes of this guide, we will use the following account ID, which was previously enrolled and validated through Face Validation. We will set the following:

• account_id : 5Vzm3vtg4wgK
• alias_id : john_doe@acme.com

If everything is correct, after sending the Create alias request, we should receive a response similar to the following:

    { 
        "alias_id": "john_doe@acme.com",
        "account_id": "5Vzm3vtg4wgK",
        "creation_date": "2024-07-27T02:20:41.285373742Z"
    }

If the alias_id already exists in your system, you will receive a 409 Conflict code:

    {
        "code": 10409,
        "http_code": 409,
        "message": "alias already exists"
    }

If no alias_id or no account_id is sent in the request, you will receive a 400 Bad Request code:

    {
        "code": 10400,
        "http_code": 400,
        "message": "Invalid request: invalid alias id: empty value"
    }

    {
        "code": 10400,
        "http_code": 400,
        "message": "Invalid request: invalid account id: empty value"
    }

NOTES:

• The alias_id must be unique within your system.
• The account_id must belong to a validated account.
• The creation_date is automatically set by the system.

Get Alias

The Get Alias request retrieves information about an existing alias. Use this to verify the alias’s existence and ensure it was created successfully before using it in other operations.

Send a GET request to the endpoint https://api.validations.truora.com/v1/aliases/{{alias_id}}. For this guides purpose, our request’s alias_id is set to john_doe@acme.com.

The response will contain the account_id associated with the alias:

    {
        "alias_id": "john_doe@acme.com",
        "account_id": "5Vzm3vtg4wgK",
        "creation_date": "2024-07-28T15:49:45.983757992Z"
    }

If the requested alias does not exist (either not created or removed), you will receive the following response:

    {
        "code": 10404,
        "http_code": 404,
        "message": "alias not found"
    }

Using aliases in Truora´s validation service

Once you’ve created an alias, you can use the alias_id instead of the account_id in Truora´s validation service.

Visit our Validators Guides to learn more about creating a validation for each case:

• Document Validation via API.
• Face Validation via API.
• Phone Validation via API.
• Email Validation via API.
• TruFace Validation.

Important Note: When both alias_id and account_id are present in a request, the account_id takes precedence. To ensure the alias is used, only include the alias_id in your request and omit the account_id.

Creating a validation

For the purpose of this guide:

• We will use the Create Validation request in Document Validation.
• We will use the alias_id body parameter set to john_doe@acme.com, which was the created alias in the previous step.
• We will omit the account_id parameter.

1. Create a POST request to the endpoint https://api.validations.truora.com/v1/validations.
2. Set the Headers
   • Truora-API-Key: Truora API-key value
   • Content-Type: application/x-www-form-urlencoded.
3. Set required values for the request body
   • type : document-validation
   • user_authorized : true
   • country : CO
   • document_type : national-id
   • alias_id : john_doe@acme.com
   • account_id : This parameter will be omitted.

In this example, the system will automatically resolve the alias_id to the correct account_id internally. Therefore, sending this request will display the created validation associated with the account_id linked to the alias_id provided in the request.

{
    "validation_id": "VLD1fb8910234a8f4ba0b0XXXXXXXX",
    "ip_address": "186.168.84.129",
    "account_id": "5Vzm3vtg4wgK",
    "type": "document-validation",
    "validation_status": "pending",
    "creation_date": "2024-07-28T19:22:34.749109732Z",
    "remaining_retries": 2,
    "instructions": {
        "front_url": "https://front_file.upload.url",
        "reverse_url": "https://reverse_file.upload.url"
    }
}

Remember, if you wish to use the alias_id, do not include the account_id in this request to ensure the alias is used. If you do not provide the alias_id, please include the account_id.

Creating an enrollment

For validators like Face Validator, Email Validator, Phone Validator, or TruFace, where an enrollment process is required to associate an account with a specific validation type, you can use the alias_id of a validated account instead of its account_id in the Create Enrollment request.

For the purpose of this guide:

• We will use the Create Enrollment request in Phone Validation.
• We will use the alias_id body parameter set to john_doe@acme.com, which was the alias used in previous steps.
• We will omit the account_id parameter.

1. Create a POST request to the endpoint https://api.validations.truora.com/v1/enrollments.
2. Set the Headers
   • Truora-API-Key: Truora API-key value
   • Content-Type: application/x-www-form-urlencoded.
3. Set required values for the request body
   • type : phone-verification
   • user_authorized : true
   • phone_number: +57314XXXXXXX
   • phone_type : office
   • alias_id : john_doe@acme.com
   • account_id : This parameter will be omitted.

In this example, the system will automatically resolve the alias_id to the correct account_id internally. Therefore, sending this request will display the created enrollment associated with the account_id linked to the alias_id provided in the request.

{
    "account_id": "5Vzm3vtg4wgK",
    "creation_date": "2024-08-28T20:20:42.749109732Z",
    "enrollment_id": "ENR124efbe465XXXXXXXXXXX",
    "validator_data": {
        "phone_trust_score": {
            "phone_behavior_score": 1
        }
    },
    "status": "success",
    "update_date": "2024-08-28T20:20:42.749109732Z",
    "validation_type": "phone-verification",
    "alias_id": "john_doe@acme.com"
}

Remember, if you wish to use the alias_id, do not include the account_id in this request to ensure the alias is used. If you do not provide the alias_id, please include the account_id.

Delete alias

In order to delete an alias you must:

• Know the alias_id you want to delete.
• Create a DELETE request to the endpoint api.validations.truora.com/v1/aliases/{{alias_id}}.

For this example, we will use the alias_id created in previous steps, john_doe@acme.com. The following success message confirms that the alias has been deleted:

    {
        "message": "alias successfully deleted"
    }

In case the alias_id does not exist or has been deleted before, you will receive the following response:

    {
        "code": 10404,
        "http_code": 404,
        "message": "alias not found"
    }

Conclusions

Implementing aliases in your Truora integration offers significant flexibility and user-friendly identity management by allowing multiple identifiers for a single validated account.

Remember to create aliases for validated accounts only. To make the most of Truora’s Alias feature:

• Review your current user identification system and identify opportunities to implement aliases.
• Start small: implement aliases in one area of your system (e.g., login process) and gradually expand.

By leveraging the power of Truora’s Alias feature, you’re not just implementing a technical solution – you’re enhancing your overall user experience and establishing a foundation for more flexible and secure identity management. We’re excited to see how you’ll use aliases to transform your identity verification processes!