# Sign up and Sign in
# Overview
The API supports two way for customers to sign up and sign in, one where they need to specify a password and another where they don't.
In the first way, to gain access to private resources, customers must use their login and password, and in the passwordless option, they will always receive an email with a magic link.
The API provides endpoints for all different options, and it also provides one endpoint for quick sign up or sign in, without needing to know whether the customer exists or not.
# Check if a customer email exists in our records
It could be useful in some scenarios to check if an email is already linked to one of the portal customers.
Issue a HEAD request to /api/rest/portal/customers/email/{email}.
Example: HEAD /api/rest/portal/customers/email/john.smith@domain.com
It will return HTTP code 200 if there's an active record for a customer with that email in our database. If there's no record with that email, it will return HTTP code 404. There's a special case, when there's a customer record, but for any reason the record was disabled, it will return HTTP code 409.
# Passwordless requests
# Passwordless access
This endpoint will send an email to the home seeker with a magic link. In case the home seeker doesn't exist as a portal customer, he will be previously registered before sending the email.
The advantage of using this endpoint is that you can use a single call to provide access to home seekers no matter if they have already an account or not.
To request the API to send an email with the magic link, issue a POST request to /api/rest/portal/passwordless-access. The payload must have the following structure:
{
"url": "Custom app url to be used when generating the magic link",
"email": "Customer email",
}
The url is the custom app url where the customer is going to be redirected, the magic link will be generated by using that url and two parameters, the id of the customer in the database, and a random generated token to be used when validating the request to get an access token. The magic link will have the format: {url}\{id}\{token}.
The API will respond with HTTP code 201 is the customer was created or 200 if the customer already existed.
If there's any validation error, the API will respond with HTTP code 422, and an object with attributes message and errors. Message will contain a general description of the error, and errors will contain the list of errors related to each parameter.
Other erroneous scenarios are possible, like when the customer exists, but for any reason he is disabled, in which case the API will also respond with HTTP code 422.
For a quick way to do tests, the email is not sent right now and if sent it will be trapped in the testing email server (MailTrap), but to allow testing the authentication process, the respond will contain an object with the field: magicLink. In the live environment, this field is not sent.
# Passwordless registration
If you want to register a new customer passwordless, with more details than just the email, issue a POST request to /api/rest/portal/passwordless-register. The customer email and the custom app url to generate the magic link are mandatory in the payload, although all customer details fields are supported and can be sent in the payload.
# Payload structure
Notice that only url and email are mandatory, although you should only send the other fields if they have a valid value.
{
"url": "Custom app url to be used when generating the magic link",
"email": "Customer email. It shouldn't exist any other customer registered with same email",
// PLUS, ANY OF THE CUSTOMER UPDATE FIELDS
}
Check the customer profile section to review all available fields related to the customer.
# Response
The API will respond with HTTP code 201 is the customer was successfully created and the email was sent to the email provided.
If there's any validation error, the API will respond with HTTP code 422, and an object with attributes message and errors. Message will contain a general description of the error, and errors will contain the list of errors related to each parameter.
# Passwordless login
To request a magic link for an existing customer, issue a POST request to /api/rest/portal/passwordless-login.
The payload and the response are similar to the ones used for Passwordless access, the only difference is that if the customer is not registered, the API will respond with a 404 error code.
# Logout
For the API the concept of logout is just revoke or delete the access token. To request the token to be revoked, issue a POST to
/api/rest/portal/revoke-token.
# Updating the email address
In some cases the customer would like to change the email address he is using to access his profile without losing any of his data.
In order to do this, two steps are required:
Issue a POST request to /api/rest/portal/passwordless-change-email for the customer to receive an email with a magic link to change his email address. The payload will be similar to other cases:
{
"url": "Custom app url to be used when generating the magic link",
"email": "Customer current email",
}
When the user click on the magic link and is redirected to your Portal again, allow him to specify the new email address and issue a PATCH request to /api/rest/portal/passwordless-change-email/{id}/{magic-link-token}, where id and magic-link-token are the last two route parameters in the url of the magic link.
The payload should contain the current email and the new one:
{
"currentEmail": "Customer current email",
"newEmail": "Customer new email",
}
If everything was OK the API will respond with status code 200, otherwise an error message and the corresponding HTTP code will be returned.
# Getting the authorization token from the magic link
Once the customer is redirected to the app when clicking on the magic link, a new request to the API should be made in order to get the access token (bearer token) to access private customer resources.
The endpoint to get the access token is:
GET /api/rest/portal/auth-token/{id}/{magic-link-token}
Where id and magic-link-token should match the values in the magic link.
Magic links can only be used once. To get a new access token you will need to generate a new magic link.
The response is a JSON object containing two attributes: accessToken and expiresAt.
To use the accessToken send the header Authorization with value Bearer {accessToken} in every request that requires authorization (access to customer private resources).
# Password full requests
# Registration
To register a new customer using email / password issue a POST request to /api/rest/portal/password-register.
# Payload structure
Notice that only email and password are mandatory. Passwords must contain at least 6 characters. You can send any customer details in the payload, but you should only send extra fields if they have a valid value.
{
"email": "Customer email. It shouldn't exist any other customer registered with same email",
"password": "Password, at least 6 characters of length",
// PLUS, ANY OF THE CUSTOMER UPDATE FIELDS
}
Check the customer profile section to review all available fields related to the customer.
# Response
The API will respond with HTTP code 201 is the customer was successfully created and a resource with all the customer fields.
If there's any validation error, the API will respond with HTTP code 422, and an object with attributes message and errors. Message will contain a general description of the error, and errors will contain the list of errors related to each parameter.
# Login
To request an access token to be able to access to the customer private resources, issue a POST request to /api/rest/portal/password-login.
The payload must have the following structure:
{
"email": "Customer email",
"password": "Customer password"
}
If the request is successful, you will receive an access_token and refresh_token in the JSON response from the server.
To use the access_token send the header Authorization with value Bearer {access_token} in every request that require authorization.
If you need to refresh the access token, issue a POST request to /api/rest/portal/refresh-token. The payload must contain a JSON with the following structure:
{
"refreshToken": "Refresh token obtained in the previous login call"
}
You will receive a response similar to the one received when asking for an access token.
# Logout
For the API the concept of logout is just revoke or delete the access token. To request the token to be revoked, issue a POST to
/api/rest/portal/revoke-token.
# Forgot password
When customers forgot their password, in order to reset it, they should provide their email address so the API can send an email with a magic link that should be used to reset the password.
To request the email with the magic link issue a POST request to /api/rest/portal/forgot-password. The payload will be similar to other cases:
{
"url": "Custom app url to be used when generating the magic link",
"email": "Customer email",
}
When the user click on the magic link and redirected to your Portal again, allow him to specify the new password and issue a POST request to /api/rest/portal/reset-password/{id}/{magic-link-token}, where id and magic-link-token are the last two route parameters in the url of the magic link.
The payload should contain only the new password:
{
"newPassword": "New customer password"
}
If everything was OK the API will respond with status code 200, otherwise an error message and the corresponding HTTP code will be returned.