Skip to main content
The account registration flow consists of three endpoints that enable new employees to create their accounts:
  1. Request registration - Initiates the registration process for an employee
  2. Validate registration token - Verifies the registration token is valid
  3. Complete registration - Creates the account with username and password
Source: RegistroCuentaController.java

​
POST /auth/register-request

Initiates the account registration process for an employee. If the employee code is valid and doesn’t have an existing account, sends a registration link to their email. Authentication: None required (public endpoint) Source: RegistroCuentaController.java:20

​
Request

​
employeeCode
string
required
The unique employee code (employee ID) assigned to the employee in the HR system.Note: For security reasons, the response is always successful regardless of whether the employee code is valid or already has an account.

​
Response

​
success
boolean
Always returns true (or null in some cases)
​
message
string
Confirmation message: “Si el colaborador es válido y no tiene cuenta, se enviará un correo.”

​
Example

curl -X POST https://api.integra.example.com/auth/register-request \
  -H "Content-Type: application/json" \
  -d '{
    "employeeCode": "EMP001"
  }'

​
Success Response

{
  "success": true,
  "message": "Si el colaborador es válido y no tiene cuenta, se enviará un correo."
}
The response is intentionally vague to prevent enumeration of valid employee codes. An email is only sent if the employee code exists and doesn’t have an associated account.

​
POST /auth/validate-registration-token

Validates that a registration token is valid and not expired. Use this endpoint to verify a token before showing the account creation form. Authentication: None required (public endpoint) Source: RegistroCuentaController.java:30

​
Request

​
token
string
required
The registration token received via email. This token is typically extracted from the registration link URL.

​
Response

Success (200 OK):
​
valid
boolean
Returns true if the token is valid and not expired
Error (400 Bad Request):
​
valid
boolean
Returns false if the token is invalid or expired
​
message
string
Error message explaining why the token is invalid

​
Example

curl -X POST https://api.integra.example.com/auth/validate-registration-token \
  -H "Content-Type: application/json" \
  -d '{
    "token": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
  }'

​
Success Response

{
  "valid": true
}

​
Error Response

{
  "valid": false,
  "message": "Token de registro inválido o expirado"
}

​
POST /auth/register-confirm

Completes the registration process by creating a new user account with the provided username and password. Authentication: None required (token-based verification) Source: RegistroCuentaController.java:41

​
Request

​
token
string
required
The valid registration token received via email
​
username
string
required
The desired username for the new account. Must be unique across the system.Requirements:
  • Must be unique (not already in use)
  • Typically 3-50 characters
  • Alphanumeric characters recommended
​
password
string
required
The password for the new account. Should meet the application’s password complexity requirements.Requirements:
  • Minimum length requirements
  • Complexity requirements (uppercase, lowercase, numbers, special characters)
  • Cannot be common or easily guessable

​
Response

Success (200 OK):
​
message
string
Success message: “Cuenta creada exitosamente.”
Error (400 Bad Request):
​
error
string
Error message explaining why the registration failed (e.g., invalid token, username already taken, weak password)
Error (500 Internal Server Error):
​
error
string
Generic error message: “Error interno al crear la cuenta.”

​
Example

curl -X POST https://api.integra.example.com/auth/register-confirm \
  -H "Content-Type: application/json" \
  -d '{
    "token": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "username": "jdoe",
    "password": "SecureP@ssw0rd123!"
  }'

​
Success Response

{
  "message": "Cuenta creada exitosamente."
}

​
Error Responses

Invalid or expired token: 
{
  "error": "Token de registro inválido o expirado"
}
Username already exists: 
{
  "error": "El nombre de usuario ya está en uso"
}
Weak password: 
{
  "error": "La contraseña no cumple con los requisitos de seguridad"
}
Server error: 
{
  "error": "Error interno al crear la cuenta."
}

​
Complete Registration Flow

Here’s how the three endpoints work together:
1

Employee requests registration

New employee enters their employee code on the registration request page. Your application calls POST /auth/register-request.
await fetch('/auth/register-request', {
  method: 'POST',
  body: JSON.stringify({ employeeCode: 'EMP001' })
});
2

Employee receives email

If the employee code is valid and has no existing account, the employee receives an email with a registration link containing a token:
https://yourapp.com/register?token=b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e
3

Validate the token

When the employee clicks the link, your application extracts the token from the URL and calls POST /auth/validate-registration-token to verify it’s valid before showing the registration form.
const response = await fetch('/auth/validate-registration-token', {
  method: 'POST',
  body: JSON.stringify({ token: urlParams.get('token') })
});

if (!response.ok || !data.valid) {
  // Show error: link expired or invalid
}
4

Employee creates account

Employee fills out the registration form with their desired username and password. Your application calls POST /auth/register-confirm.
await fetch('/auth/register-confirm', {
  method: 'POST',
  body: JSON.stringify({
    token: registrationToken,
    username: formData.username,
    password: formData.password
  })
});
5

Redirect to login

After successful registration, redirect the employee to the login page to sign in with their new credentials.
Registration tokens are single-use and expire after a set period (typically 24-48 hours). Once an account is successfully created, the token is invalidated and cannot be reused.
Always validate the token before showing the registration form to provide immediate feedback if the link has expired or is invalid.
The employee code must correspond to an existing employee record in the HR system. Employees cannot register without a valid employee code, ensuring only authorized personnel can create accounts.

Build docs developers (and LLMs) love

Get started for freeTalk to us