Step 4: Refresh your Access Token

To ensure uninterrupted access to protected resources in the Nxsys system, you must refresh your access token before it expires. This process uses a refresh token to obtain a new access token without requiring re-authentication. Follow the steps below to implement token refresh in your application.

Steps to Refresh an Access Token

1. Monitor Token Expiration

Before initiating API requests, verify whether the current access token is nearing its expiration time. Implement logic to check the token's expiry (typically included in the token response as expires_in) to proactively trigger a refresh.

2. Prepare the Refresh Request

When the access token is close to expiring, construct a POST request to the Nxsys token endpoint to obtain a new access token.

3. Include Required Parameters

Include the refresh token, along with your application's credentials, in the request body. The required parameters are outlined below:

Parameter	Type	Required	Description
`grantType`	String	Yes	Must be set to `refresh_token`.
`refreshToken`	String	Yes	The refresh token issued with the original access token.
`clientId`	String	Yes	The unique client ID assigned to your application.
`clientSecret`	String	Yes	The client secret associated with your application for secure authentication.

4. Send the Refresh Request

Submit the POST request to the Nxsys token endpoint. Below is an example using curl:

Nxsys Base API URL
For guidance on configuring the base URL for different environments, refer to Base URL and Environments.

5. Process the Response

Upon successful request, the Nxsys token endpoint returns a JSON response containing the new access token and, optionally, a new refresh token. Parse the response to extract these values.

Example Response:

{
  "accessToken": "NEW_ACCESS_TOKEN",
  "refreshToken": "NEW_REFRESH_TOKEN",
  "expiresIn": 3600,
  "tokenType": "Nxsys-oauthtoken"
}

6. Update Stored Tokens

Securely store the new access token and, if provided, the new refresh token in your application's storage. Replace the old tokens to ensure subsequent API requests use the updated credentials.

7. Resume API Operations

Use the new access token in the Authorization header (e.g., Bearer Nxsys-oauthtoken NEW_ACCESS_TOKEN) for all subsequent API requests to Nxsys endpoints.

Example Implementation

Below is a sample JavaScript implementation using the Fetch API to refresh an access token:

📌 Notes

Replace YOUR_REFRESH_TOKEN, YOUR_CLIENT_ID, and YOUR_CLIENT_SECRET with your actual credentials.

Ensure your application handles errors gracefully, such as invalid refresh tokens or network issues.

For enhanced security, store tokens in a secure manner (e.g., encrypted storage) and avoid exposing sensitive data in logs or client-side code.

Error Handling

If the refresh request fails, the API may return errors such as:

Error Code	Description	Suggested Action
`invalid_grant`	Invalid or expired refresh token	Re-authenticate to obtain a new refresh token
`invalid_client`	Incorrect `clientId` or `clientSecret`	Verify your client credentials
`400 Bad Request`	Missing or malformed request parameters	Check the request body for accuracy

For additional details on error codes, refer to Handling Errors.

Steps to Refresh an Access Token#

1. Monitor Token Expiration#

2. Prepare the Refresh Request#

3. Include Required Parameters#

4. Send the Refresh Request#

5. Process the Response#

6. Update Stored Tokens#

7. Resume API Operations#

Example Implementation#

📌 Notes#

Error Handling#