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
Use this endpoint to create a new user account by providing your first name, surname, email address, and password.

Once submitted, the system creates the account and sends a confirmation code to the provided email address. You’ll need to verify this code to activate your account via the Account Confirmation endpoint.

When to use:
This endpoint is used during the signup process on our platform, allowing users to register directly through the app or website.

How it works:
Provide your details – Enter your first name, surname, email, and password.
Send a POST request – The information is sent to our system to create your account.
Check your email – If successful, you’ll get a confirmation message.
Activate your account – Complete signup 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 is used to confirm and activate a newly created user account. After a user signs up, a unique confirmation code is automatically sent to their email. This code is required to verify the user's identity and complete the registration process. By submitting the confirmation code along with the email address used during signup, the account will be marked as confirmed and fully activated.

When to use:
Use this endpoint after signing up, when you’ve received a confirmation code and are ready to activate your account.

How it works:
1️⃣ Enter your email and code – Provide the confirmation code and the email address used during signup.
2️⃣ Verify your identity – The system checks the code for accuracy and expiration.
3️⃣ Account activation – If valid, your account is confirmed and ready to use.
4️⃣ Invalid code? – If the code is incorrect or expired, an error is returned and you’ll need to request a new one.
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 is used to resend a confirmation code to a user's email address when the original code has been lost, expired, or not received. It helps users complete the signup process if they were unable to activate their account using the first code. To receive a new code, simply provide the email address used during registration.

Common use case:
If the original confirmation code has expired, was never received, or was accidentally deleted.

How it works:
1️⃣ Enter your email – Provide the same email address used during signup.
2️⃣ Request a new code – The system generates and sends a new confirmation code.
3️⃣ Check your inbox – Use the new code to confirm your account via the Account Confirmation endpoint.
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 is used to log in to your account securely by submitting your registered email address and password. When the provided credentials are correct, the system verifies your identity and grants access to your account.

When to use:
After confirming your account to sign in and start using the platform.

How it works:
1️⃣ Enter your login details – Provide the email and password you used during signup.
2️⃣ Authentication – The system checks your credentials.
3️⃣ Success – If valid, you're logged in and granted access.
4️⃣ Failure – If incorrect, an error message explains what went wrong (e.g., 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 is used to securely log out of your account by ending your current session. Once logged out, you will no longer have access to protected areas of the platform until you log in again.

Typical scenario:
A user logs out through a sign-out action in the application, ending access to protected resources.

How it works:
1️⃣ Send a logout request – This signals the system to end the active session.
2️⃣ Session ends – The user's access is revoked immediately.
3️⃣ Protected features blocked – Any further actions that require login will be denied until the user signs 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 endpoint is used to complete the password recovery process by verifying the confirmation code and setting a new password. After initiating a password reset, you will receive a confirmation code by email. To reset your password, submit your email, the confirmation code, and your new password.

Use this after you've received a password reset code via email and are ready to set a new password for your account.

How it works:
1️⃣ Provide required details – Submit your email, the code you received, and a new password.
2️⃣ Verification – The system checks the code and validates the input.
3️⃣ Password updated – If successful, your password will be changed and you can log in with the new credentials.

When to use:
Use this when you forget your password and need to reset it to regain access to your account.

How it works:
1️⃣ Enter your email – Submit the email address you used to sign up.
2️⃣ Get a confirmation code – The system will send a password reset code to your inbox.
3️⃣ Proceed to reset – Use the Confirm Password Recovery endpoint to enter the code and set a new password.

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 endpoint is used to change your current account password. To update your password, you need to provide your current password and a new password that you want to set.

Use this endpoint when you're logged in and want to change your password for security or personal reasons.

How it works:
1️⃣ Submit your current password – This is required to confirm your identity.
2️⃣ Provide a new password – Choose a secure new password to replace the old one.
3️⃣ Receive confirmation – If the current password is correct and the new password is valid, the update will be successful.

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).