Nxsys API Documentation
  1. Authentication
Nxsys API Documentation
  • Introduction
    • Nxsys API Documentation
    • Base URL and Environments
    • Handling Errors
    • Pagination
    • Best Practices
  • Authentication
    • Overview
    • Step 1: Create a Client Application
    • Step 2: Obtain Authorization Code
    • Step 3: Exchange your Authorization Code for an Access Token
    • Step 4: Refresh your Access Token
  • APIs
    • Authentication
      • Construct the Authorization URL
      • Exchange your Authorization Code for an Access Token
    • Candidates
      • Create Candidate
      • Get Candidates
      • Update Candidate
    • VAT Codes
      • Get Default VAT Codes
    • PaymentRate
      • Create Payment Rate
      • Get Payment Rates
      • Get Single Payment Rate
      • Update Payment Rate
    • Timesheet
      • Create Timesheet
      • Get Timesheets
      • Get Single Timesheet
      • Update Timesheet
    • Payslips
      • Get Payslips
  1. Authentication

Step 2: Obtain Authorization Code

To use the Nxsys API, the users must authenticate on every API call by providing the Access Token.
The access token, in return, must be obtained from a grant token (authorization code). The Nxsys APIs use the authorization code grant type to provide access to protected resources.

Prerequisites#

Client ID
Client Secret
Redirect URI
📌
If you don't have a client ID, client secret, and redirect URI, you can create a client application in the Nxsys Admin.
Step 1: Create a Client Application

Steps to Obtain Authorization Code#

1
Construct the Authorization URL
The Nxsys OAuth authorization URL is used to initiate the authorization code grant flow. The URL structure is:
{{nxsys_base_url}}/oauth/authorize?responseType=code&clientId={{client_id}}&redirectUri={{redirect_uri}}&state={{state}}
URL Parameters
ParameterDescription
{{nxsys_base_url}}The Authorization Base URL for the Nxsys API (e.g., https://portal.nxsys.tech). View more information about Base URL and Environments.
responseTypeSet to code to indicate the authorization code grant type, returning an authorization code upon successful user authentication.
clientIdThe unique identifier for the client application, obtained during client registration with Nxsys. Replace {{client_id}} with the actual client ID.
redirectUriThe URL where the user is redirected after authorization. It must match the URI registered with Nxsys. Replace {{redirect_uri}} with the actual redirect URI.
stateA unique, randomly generated string to maintain state between the request and callback, helping prevent CSRF attacks. Replace {{state}} with a unique value.
Example URL
For a base URL of https://api.nxsys.tech, a client ID of abc123, a redirect URI of https://yourapp.com/callback, and a state of xyz789, the constructed URL is:
https://api.nxsys.tech/oauth/authorize?responseType=code&clientId=NXSYS.ONZEYLYLO38TL9XEBE3JQUPGTYUQMZ7S&redirectUri=https://yourapp.com/callback&state=xyz789
2
Redirect the User
Direct the user to the constructed authorization URL. Upon accessing this URL, the user will be prompted to log in to their Nxsys account and authorize your application to access the requested resources. Ensure that {{client_id}}, {{redirect_uri}}, and {{state}} are replaced with your application-specific values.
Ensure the redirectUri matches the one registered with Nxsys to avoid authorization errors.
3
Handle the Callback
After the user authorizes your application, Nxsys redirects them to the redirectUri specified in the authorization URL. The redirect URL includes a code parameter containing the authorization code and the state parameter you provided. The callback URL will have the following structure:
{{redirect_uri}}?code={{authorization_code}}&state={{state}}
The state parameter should be a unique, unpredictable value for each authorization request to enhance security.
** Example Callback URL**
Using the redirect URI https://yourapp.com/callback, the callback URL might look like:
https://yourapp.com/callback?code=6ac64d880b1a74fd3c1c012973dcb8c4&state=xyz789
4
Verify the State
To ensure the security of the authorization process and prevent cross-site request forgery (CSRF) attacks, verify that the state parameter returned in the callback URL matches the state value you sent in the authorization URL. If the values do not match, reject the response and do not proceed with the authorization code.
5
Extract the Authorization Code
Extract the code parameter from the callback URL. This authorization code is a temporary token used to obtain an access token in the next step of the OAuth flow (e.g., via a token exchange request). Store the code securely and use it promptly, as it typically has a short expiration time.
The authorization code is short-lived and can only be used once. Typically, it expires after 10 minutes.
📌

You can quickly generate authorzation url using Construct the Authorization URL#

Next, you'll use this authorization code to Step 3: Exchange your Authorization Code for an Access Token.
Previous
Step 1: Create a Client Application
Next
Step 3: Exchange your Authorization Code for an Access Token
Built with