Home
Home
  1. API Reference
  • Salary Deduction
    • Welcome
    • Getting started
      • Availability and Onboarding
        • Light Availability Check
        • Full Availability Check
        • Onboarding
      • Salary Deduction
        • Deduction Instruction
        • Re-running Payroll
        • Deduction Payments and Reconciliation
        • Changes to Employee Status
    • API Reference
      • Authentication
      • Idempotency
      • Webhooks
        • Webhooks
      • Salary Deduction
        • Salary Deduction Data Request
        • Salary Deduction Confirmation Submission
    • Schemas
      • Availability Check
        • Light Availability Check Response
        • Light Availability Check Request
        • Full Availability Check Response
        • Full Availability Check Request
      • Core
        • ProblemDetails
      • Deduction Instructions
        • Salary Deduction
        • Confirmation Deduction Response
        • Salary Deduction Enablement Response
        • Employee Deduction Push Response
        • Employee Deduction Push Request
        • Latest Employee Deduction Push Response
      • Payment Account
        • Payment Account
        • Payment Information
      • Payroll
        • Salary Deduction Confirmation Data Submission
        • Salary Deduction Data Response
        • Payroll
        • Employee Payroll
        • Employment
        • Pay Date
        • Salary Deduction Enablement Request
      • Webhooks
        • Employee Update Payload
        • WebHook
  • Payroll Provider API Prototypes
    • Light Availability Check
      POST
    • Full Availability Check
      POST
    • Salary Deduction Enablement
      POST
    • Payroll Information
      GET
    • Salary Deduction Employee Data Push
      POST
    • Latest Salary Deduction Employee Data Push
      GET
  1. API Reference

Authentication

Overview#

Ontime uses the OAuth2 Client Credentials Flow for secure, machine-to-machine (M2M) authentication. This flow allows services to authenticate and interact with Ontime’s APIs without user involvement.
MechanismUsed forSend with
OAuth 2 Client‑CredentialsAll APIsAuthorization: Bearer [access‑token]
Static API KeyAll APIsx-api-key: [key]

Benefits of OAuth2#

Enhanced Security – OAuth eliminates the need for applications to store or transmit user credentials, reducing the risk of password-related attacks.
Granular Access Control – Applications can request specific permissions (scopes), ensuring they only access the data or functionality they need.
Revocable and Time-Limited Access – Tokens issued through OAuth can be short-lived and revoked at any time, reducing security risks if credentials are compromised.
Standardisation and Interoperability – Widely adopted across platforms and services, OAuth provides a consistent and scalable way to manage authentication and authorisation across different systems.
1
Token Request
The client sends a request to the OAuth authorisation server with its credentials (client_id, client_secret) and requested scope.
2
Token Issuance
If valid, the OAuth server returns an access token to the client.
3
API Request
The client makes a [verb]/[endpoint] request to the Backend API, attaching the access token in the Authorisation header.
4
Token Validation
The Backend API validates the access token with the OAuth server.
5
Approval
The server verified the token is valid and has the necessary permissions to access the resource.
6
Response
The Backend API processes the request and returns the appropriate response.
By leveraging OAuth, organisations can ensure secure, controlled, and user-friendly access to their APIs and services while maintaining robust security and compliance.

OAuth2 Client Credentials Flow#

OAuth2 Client Credentials Flow
The OAuth2 Client Credentials Flow authentication method is designed for machine-to-machine communication. It allows applications to authenticate without requiring user interaction.

Essential headers#

Every Ontime API request must include:
✅ A valid OAuth2 Bearer Token
✅ A valid API Key in the request header

Scoped Access#

API access is controlled through OAuth scopes, ensuring that applications only have permissions necessary for specific actions.
ScopePermission
deductions:readCan read deductions to be made
confirmations:writeCan upload confirmation files
deduction_data:requestCan request salary deduction data
deduction_data_confirmation:submitCan submit deduction data confirmation
notifications:writeCan send webhooks to Ontime
Scopes define what actions your application can perform
Limiting requested OAuth scopes to only those required for each API request is a fundamental security best practice that helps minimise the threat surface area by enforcing the principle of least privilege.
By restricting access to only the necessary permissions, organisations reduce the potential impact of a compromised token, mitigating risks such as unauthorised data access, privilege escalation, and lateral movement within systems. This approach also enhances compliance with data protection regulations by ensuring sensitive data is accessed only when explicitly needed. Additionally, it limits exposure in case of an API misconfiguration or vulnerability, reducing the risk of data breaches and unauthorised transactions.

Endpoints you host#

Ontime calls the Payroll Provider API endpoints you host (Light Availability Check, Full Availability Check, Salary Deduction Enablement, Payroll Information, Salary Deduction Employee Data Push and Latest Salary Deduction Employee Data Push) with:
✅ Authorization: Bearer [access-token], a token Ontime gets from your OAuth 2.0 client-credentials server
✅ x-api-key: [key], an API key you issue to Ontime
You define the token server, the scopes, and how the credentials are issued and rotated. Ontime does not define scopes for these endpoints.

Obtaining Credentials#

Your client_id, client_secret, and API key will be provided through a secure link.

Obtaining an OAuth2 Token#

To obtain an OAuth2 token, send a POST request to our token server
EnvironmentUrl
Developmenthttps://payments-domain-development.auth.eu-west-2.amazoncognito.com
Productionhttps://payments-domain-production.auth.eu-west-2.amazoncognito.com

Security Best Practices#

Security Best Practices
Never expose client_id or client_secret in client-side applications (e.g., web browsers, mobile apps).
Store secrets securely using environment variables or a secrets manager.
Example using Curl
Request:
curl -X POST "https://tokenserver.co.uk/oauth/token" \
   -H "Content-Type: application/x-www-form-urlencoded" \
   -d "grant_type=client_credentials" \
   -d "client_id=YOUR_CLIENT_ID" \
   -d "client_secret=YOUR_CLIENT_SECRET" \
   -d "scope=payments:write"
Response:
{
  "access_token": "your_generated_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Making API requests#

Once you have obtained the token, include it in your API requests along with your API key.
API Base URL: https://api.ontime.co
Example using Curl
Request:
curl -X GET "https://api.ontime.co/payments" \
   -H "Authorization: Bearer YOUR_GENERATED_TOKEN" \
   -H "x-api-key: YOUR_API_KEY"
Previous
Changes to Employee Status
Next
Idempotency