Authentication

This endpoint exchanges client credentials (ID and secret) for an authentication token. The obtained auth token should be used in the Authorization header for making authenticated requests to other endpoints.

HTTP Method

POST

The POST HTTP method is used because we are submitting data (Client ID and Client Secret) to the server to create a new resource (authentication token). In this case, the server processes the request and returns an access_token and a refresh_token in response.

Endpoint

/authenticate

cURL Request Example

curl --request POST \
     --url https://api-sandbox.niural.com/authenticate \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "client_id": "7a9f4-9c2-48b8-8c3e-369de7d79a",
  "client_secret": "*****************"
}
'

Body Parameters

• client_id: The Client ID is a UUID (Universally Unique Identifier) that is provided by Niural when the client registers for API access. It uniquely identifies the client application making the request.
• client_secret: The Client Secret is similar to a password, and it is paired with the Client ID to authenticate the client. It should never be shared or exposed publicly, as it provides access to the API.

Example Request Body:

{
  "client_id": "7a9f4-9c2-48b8-8c3e-369de7d79a",
  "client_secret": "******************"
}

This JSON object is what you send in the body of the POST request. It includes the client_id and client_secret as key-value pairs, which are required to authenticate and retrieve the access token.

Headers

• Content-Type: This header indicates the format of the data being sent in the request. In this case, we are sending the data in JSON format (application/json).
• Accept: This header tells the server that the client expects the response to be in JSON format (application/json).

Response Example

• Successful Response (200):

{
  "data": {
    "access_token": "eyJhGciOJIUzI1NiIsInR5cCI",
    "refresh_token": "b0ee937-a41-46d4-b7a1",
    "expires_in": 3600
  }
}

When the request is successful, the server responds with a 200 OK status and returns a JSON object containing three key pieces of information:

• access_token: This is the token you will use to authenticate all future API requests. It should be included in the Authorization header as Bearer \<access_token>.
• refresh_token: This token is used to refresh the access_token when it expires. This means you don’t need to provide the client_id and client_secret again.
• expires_in: This specifies how long (in seconds) the access_token is valid before it expires and needs to be refreshed. In this example, it is valid for 3600 seconds (1 hour).

Response Fields

These fields are included in the response, and they are essential for maintaining session-based access to the API. The access_token is needed for authentication, the refresh_token extends session life without re-entering credentials, and expires_in helps you manage token expiration.

Errors

• 400 Bad Request : If the client_id or client_secret is missing or invalid, you will receive a 400 Bad Request error. This indicates that there is an issue with the data being sent in the request.
• 500 Internal Server Error: A 500 Internal Server Error occurs when there is a problem on the server side. This could be due to an unexpected failure, system downtime, or a bug in the server code.

How to Use the Access Token?

Once you have received the access_token, you must include it in the Authorization header of all subsequent API requests to authenticate yours

Authorization: Bearer <access_token>

This step is crucial. All further API requests require this token to verify your identity and authorize access to specific endpoints. If you don’t include the token, you will receive a 401 Unauthorized error.

Token Expiry and Refreshing

When the access token expires (as indicated by the expires_in field), you can use the refresh_token to obtain a new access token without re-entering your client_id and client_secret.

Notes

• After receiving the access_token, include it in the Authorization header as Bearer <token> in subsequent requests to authenticate.
• The refresh_token can be used to generate a new access token without needing to provide the client_id and client_secret again.
• The expires_in field specifies how long the token remains valid before it needs to be refreshed.