Authentication
Authentication is the process of confirming the identity of a user or system before granting access to resources. In this API, authentication ensures that only authorized users or applications can perform sensitive actions, such as updating account details or managing private data.

This API uses token-based authentication, where a token is generated during login or authorization. This token is then used to authenticate future requests. Compared to traditional methods like API keys, token-based authentication is more secure and flexible. Tokens can be configured with specific permissions, revoked if necessary, and set to expire after a defined period.

The standard authentication flow follows these steps:

  1. Login/Token Generation: The user or system submits credentials, which the server verifies before issuing a token.
  2. Use Token in API Requests: For requests that require authentication, the token is included in the request headers as Authorization: Bearer <your_token_here>.
  3. Token Validation: The server checks the token's validity. If valid, the request proceeds. If invalid, access is denied.

This approach provides enhanced security and control, allowing fine-grained access management while safeguarding sensitive information.
ENDPOINTS
Expand all
  • Account setup
    POST/v1/account
    PATCH/v1/account
    POST/v1/account/confirmation-code
  • User onboarding
  • Password management
Account Sign Up
This endpoint allows you to create a new user account by providing the required details, including your first name, surname, email, and password. After successfully creating your account, a confirmation code will be sent to your email address. The system will respond with a message indicating whether your registration was successful or, if applicable, provide error details if the user already exists.
To finalize your account setup, complete the process via the Account Confirmation endpoint.
Request Body Parameters
  • name string
    First name of the user.
  • surname string
  • email string
  • password string
JavaScript
Response codes
const axios = require('axios');

const requestBody = {
    name: "John",
    surname: "Smith",
    email: "example@gmail.com",
    password: "examplePassw0rd!"
};

axios.post('https://auth.api.pinghome.io/v1/account', requestBody)
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error(error);
    });
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Account Confirmation
This endpoint allows you to confirm your account by entering the confirmation code that was sent to your email address during the sign up process. To complete the confirmation, provide your confirmation_code along with youremail. Once the information is verified, the API will update your account status to confirm your identity. This final step activates your account, granting you access to all features and services associated with it. If the confirmation code is invalid or expired, an error message will be returned, prompting you to request a new code.
Request Body Parameters
  • email string
    The user's email address.
  • confirmation_code string
JavaScript
Response codes
const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/account';
const requestBody = {
    email: 'pinghome@gmail.com',
    confirmation_code: '876112',
    }
};

axios.patch(url, requestBody)
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Resend Sign up Confirmation Code
This endpoint allows you to request a new confirmation code to verify your email address if the original code was lost or expired. To request a new code, provide the email address associated with your account. Upon success, a new confirmation code will be sent to the specified email address, enabling you to complete the account verification process .
Request Body Parameters
  • email string
    The email address where the confirmation code should be sent.
JavaScript
Response codes
const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/account/confirmation-code';
const requestBody = {
    email: 'user@example.com'
};

axios.post(url, requestBody)
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Account Sign In
This endpoint allows you to securely access your account by providing your email and password.

Expected Behavior:


  • When the credentials are correct, the system will authenticate you and return authentication tokens along with your account details, granting you access to the system.
  • If the credentials are incorrect or the request is unauthorized, the system will return an error message explaining the issue, such as an invalid email or password.
Request Body Parameters
  • email string
    The user's email address used for authentication.
  • password string
JavaScript
Response codes
const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/auth';
const requestBody = {
    email: 'pinghome@gmail.com',
    password: 'TestPassw0rd!'
};

axios.post(url, requestBody)
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Logout & Revoke Access
This endpoint allows you to securely log out by ending your current session. Once the session is ended, you will be logged out and will no longer have access to protected areas of the system until you log in again.

Authorization: Bearer YOUR_TOKEN



Expected Behavior:


  • The system will log you out, revoke your session, and invalidate any related tokens.
  • If the request is unauthorized or invalid, the system will respond with an error message explaining the issue.
JavaScript
Response codes
const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/auth';

axios.delete(url, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
})
.then(response => {
    if (response.status === 204) {
        console.log('Session deleted successfully');
    }
})
.catch(error => {
    console.error(error.response.data);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Recover Password
This API allows you to recover your password by initiating the password reset process. To trigger the recovery, you need to submit your email. Once the request is processed, the system will send a confirmation code to the provided email address.

Expected Behavior:


  • On success, you will receive an email containing a confirmation code to reset your password.
  • Use the Confirm Password Recovery endpoint to verify the confirmation code you received via email.
  • If the email address is invalid or the request fails, an error message will be returned explaining the issue.
Request Body Parameters
  • email string
    The email address of the user requesting password recovery.
JavaScript
Response codes
const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/account/password';
const requestBody = {
    email: 'pinghome@gmail.com'
};

axios.post(url, requestBody)
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Confirm Password Recovery
This API endpoint finalizes the password recovery process by allowing you to provide a recovery code and set a new password. After requesting a password reset, you will receive a confirmation code via email. To complete the process, submit your confirmation code, email and newpassword. Upon successful submission, the password will be updated.

Expected Behavior:


  • On success, your password will be updated.
  • If the recovery code is incorrect or the request is invalid, an error message will be returned.
Query parameters
  • email string
    The email address of the user confirming the password recovery.
  • code string
  • password string
JavaScript
Response codes
const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/account/password';
const requestBody = {
    email: 'pinghome@gmail.com',
    code: '285009',
    password: 'UpdatedPassw0rd!'
};

axios.patch(url, requestBody)
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Update Account Password
This API endpoint allows you to change your current password. You must provide your previous_password and the new proposed_password you wish to set.

Authorization: Bearer YOUR_TOKEN



Expected Behavior:


  • On success, the system will update the password and return a confirmation message.
  • If the request is unauthorized or invalid, the system will respond with an error message.
Request Body Parameters
  • previous_password string
    The current password of the user.
  • proposed_password string
JavaScript
Response codes
const axios = require('axios');

const url = 'https://auth.api.pinghome.io/v1/account/password';
const requestBody = {
    previous_password: 'UpdatedPassw0rd!',
    proposed_password: 'TestPassw0rd!'
};

axios.put(url, requestBody, {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).