Home
Home
  1. API Reference
  • 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
  • Payroll Provider Reference Implementation
    • Light Availability Check
      POST
    • Full Availability Check
      POST
    • Salary Deduction Enablement
      POST
    • Payroll Information
      GET
    • Salary Deduction Employee Data Push
      POST
  • Schemas
    • Availability Check
      • Full Availability Check Request
      • Full Availability Check Response
      • Light Availability Check Request
      • Light Availability Check Response
    • Core
      • ProblemDetails
      • MetaData
      • Paged Response
    • Deduction Instructions
      • Salary Deduction Request
      • Salary Deduction
      • Confirmation Deduction Response
      • Salary Deduction Enablement Response
      • Employee Deduction Push Response
      • Employee Deduction Push Request
      • Salary Deduction Push
      • InstructionFile
      • InstructionItem
    • Payment Account
      • Payment Account
      • Payment Information
    • Payroll
      • Employee
      • Availability Payroll
      • Availability Employment
      • Availability Employer
      • BeneficiaryAccountResponse
      • Salary Deduction Confirmation Data Submission
      • Salary Deduction Confirmation Data Submission Response
      • Salary Deduction Data Request
      • Salary Deduction Data Response
      • Payroll
      • Employee Payroll
      • Employment
      • Employer
      • Pay Date
      • Salary Deduction Enablement Request
      • PayrollScheduleResponse
    • Webhooks
      • Employee Update Payload
      • WebHook
  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 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
light_availability:submitCan submit Light Availability Check requests
full_availability:submitCan submit Full Availability Check requests
confirmations:writeCan upload confirmation files
deduction_data:requestCan request salary deduction data
deduction_data_confirmation:submitCan submit deduction data confirmation
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.

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