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
      • Get url to connect Nxsys system
      • Get access token
    • Candidates
      • Create Candidate
      • Get Candidates
      • Update Candidate
      • Get Candidate by ID
    • Candidates Ireland
      • ClientCandidatesIrelandController_createIrelandCandidate
      • Get Candidates
      • Update Candidate
      • Get Candidate by ID
    • VAT Codes
      • Get list default VAT Code
    • PaymentRate
      • Create new Payment Rate
      • OpenAPIPaymentRateController_findAllPaymentRates
      • OpenAPIPaymentRateController_findPaymentRateById
      • Update Payment Rate
    • Timesheet
      • Create timesheets
      • OpenAPITimesheetController_findAllTimeSheet
      • OpenAPITimesheetController_findTimeSheetById
      • OpenAPITimesheetController_editTimeSheetById
    • Payslips
      • Get list payslips (v2)
      • Get Payslips (v1 — legacy shape)
    • Documents
      • Create document on Employee profile
      • Get list of documents for Employee
      • Get document by id
      • Update document
      • Delete document
  • Authorization
    • Get OAuth client info for the consent screen
      GET
  • Schemas
    • Schemas
      • AgencyCreateDto
    • PensionSettingDTO
    • GeneralSettingDTO
    • BankSettingDTO
    • OpeningBalanceDTO
    • PayrollSettingDTO
    • CreateCandidateDTO
    • GeneralSettingUpdateDTO
    • PayrollSettingUpdateDTO
    • UpdateCandidateDTO
    • IrelandGeneralSettingDTO
    • IrelandBankSettingDTO
    • IrelandPayrollSettingDTO
    • CreateIrelandCandidateDTO
    • UpdateIrelandGeneralSettingDTO
    • UpdateIrelandBankSettingDTO
    • UpdateIrelandPayrollSettingDTO
    • UpdateIrelandCandidateDTO
    • PayslipCandidateDto
    • PayslipCompanyDto
    • PayslipAmountsDto
    • PayslipEarningDto
    • PayslipLineDto
    • UkPayeStatutoryDto
    • PayslipHolidayAccrualDto
    • UkEmployerCostsDto
    • UkPayeYtdDto
    • UkPayeBreakdownDto
    • IrelandPayeYtdDto
    • IrelandPayeBreakdownDto
    • CisBreakdownDto
    • PayslipBreakdownDto
    • PayslipAgencyDto
    • PartnerPayslipDto
    • PartnerPayslipListResponseDto
    • PaymentRateCreateDto
    • PaymentRateEditDto
    • OpenAPIRateTimeSheet
    • OpenAPITimeSheetCreateDto
    • OpenAPITimeSheetEditDto
    • OpenAPIDocumentCreateDto
    • OpenAPIDocumentEditDto
  1. Authentication

Overview

📌
Heads up — new sign-in experience. Nxsys has moved to a new UI at https://app.nxsys.tech. This is now where you create client applications (Step 1) and where the OAuth authorization/consent screen is served (Step 2). The legacy UI is still available at legacy-portal.nxsys.tech (Umbrella) and legacy-payroll.nxsys.tech (Payroll).
If your integration builds the authorization URL dynamically or via the grant token URL endpoint (recommended), no change is required.
If you hard-coded an older domain such as portal.nxsys.tech or payroll.nxsys.tech, update it to https://app.nxsys.tech.
The Nxsys API uses OAuth 2.0 as its authentication mechanism.

Why OAuth 2.0?#

OAuth 2.0 is a widely adopted authorization framework that enables third-party applications to gain limited access to user accounts on an HTTP service—without requiring the user to share their credentials.
It works by:
Delegating user authentication to the service hosting the account
Authorizing third-party applications to access specific user data securely

OAuth 2.0 Authorization Flows#

There are four primary OAuth 2.0 flows, depending on the use case (e.g., web apps, mobile apps, machine-to-machine):

Typical Steps in the Flow:#

1.
Register a client application
2.
Obtain a Client ID and Client Secret
3.
Redirect the user to obtain an authorization code
4.
Exchange the authorization code for an access token
5.
Refresh the access token when it expires

What You Need to Prepare#

To integrate with the Nxsys API via OAuth 2.0, you’ll need to prepare the following:

Redirect URL (Callback URL)#

The redirect URL is a key component of the OAuth flow. It’s the endpoint in your application where users are redirected after they authenticate with Nxsys.
To configure this properly:
Use a secure (HTTPS) URL within your application
Ensure the endpoint is capable of handling the OAuth response (e.g., parsing the authorization code)
Register this URL with Nxsys when setting up your client application
Example:
https://{{your domain}}/oauth/callback
📌
Important: Always use HTTPS for your redirect URL to ensure secure communication and protect against interception attacks.
Previous
Best Practices
Next
Step 1: Create a Client Application
Built with