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:
- Users can interact with your system using their preferred identifier, enhancing convenience and satisfaction.
- By linking all identifiers to a single validated account, you maintain the integrity of your identity verification process.
- 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:
- User registration and login systems.
- Account recovery processes.
- 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:
-
You have created an account for the user. Please visit Create an Account ID to learn more about it.
-
The account has successfully completed the validation process.
-
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:
Create alias
Setup main Request Headers and Body
To configure the main request headers and body, follow these steps:
-
Create a
POST
request to the endpointhttps://api.validations.truora.com/v1/aliases
-
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 beapplication/x-www-form-urlencoded
.
-
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
: 5Vzm3vtg4wgKalias_id
:john_doe@acme.com
If everything is correct, after sending the Create alias request, we should receive a response similar to the following:
/v1/aliases
If the alias_id
already exists in your system, you will receive a 409 Conflict code:
/v1/aliases
If no alias_id
or no account_id
is sent in the request, you will receive a 400 Bad Request code:
/v1/aliases
/v1/aliases
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:
/v1/aliases/{{alias_id}}
If the requested alias does not exist (either not created or removed), you will receive the following response:
/v1/aliases/{{alias_id}}
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
andaccount_id
are present in a request, theaccount_id
takes precedence. To ensure the alias is used, only include thealias_id
in your request and omit theaccount_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 tojohn_doe@acme.com
, which was the created alias in the previous step. - We will omit the
account_id
parameter.
- Create a
POST
request to the endpointhttps://api.validations.truora.com/v1/validations
. - Set the Headers
Truora-API-Key
: Truora API-key valueContent-Type
:application/x-www-form-urlencoded
.
- Set required values for the request body
type
: document-validationuser_authorized
: truecountry
: COdocument_type
: national-idalias_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.
/v1/validations
Remember, if you wish to use the
alias_id
, do not include theaccount_id
in this request to ensure the alias is used. If you do not provide thealias_id
, please include theaccount_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 tojohn_doe@acme.com
, which was the alias used in previous steps. - We will omit the
account_id
parameter.
- Create a
POST
request to the endpointhttps://api.validations.truora.com/v1/enrollments
. - Set the Headers
Truora-API-Key
: Truora API-key valueContent-Type
:application/x-www-form-urlencoded
.
- Set required values for the request body
type
: phone-verificationuser_authorized
: truephone_number
: +57314XXXXXXXphone_type
: officealias_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.
/v1/enrollments
Remember, if you wish to use the
alias_id
, do not include theaccount_id
in this request to ensure the alias is used. If you do not provide thealias_id
, please include theaccount_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:
/v1/aliases/{{alias_id}}
In case the alias_id
does not exist or has been deleted before, you will receive the following response:
/v1/aliases/{{alias_id}}
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!