Home
Home
  1. Home
  • Welcome
    • About Ontime
    • Overview
    • Test and Learn Projects
  • Authentication
  • Availability Check
    • Light Availability Check
      POST
    • Full Availability Check
      POST
  • Payment Management
    • Mandates
      • Create a new mandate
      • Cancel an existing mandate
      • Get a Mandate
      • Get many Mandates
    • Payment Requests
      • Instruct a new payment request
      • Cancel an existing payment request
      • Get a Payment
      • Get many Payments
  • Payouts
    • Get a Payout
      GET
    • Get Available Payouts
      GET
  • Webhooks
    • Mandate Created/Updated
    • Payment Request Created/Updated
    • Payout Created
  1. Home

Authentication & API Access

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 (payments:write).
2
Token Issuance
If valid, the OAuth server returns an access token to the client.
3
API Request
The client makes a POST /payments request to the Payments API, attaching the access token in the Authorisation header.
4
Token Validation
The Payments 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 Payments 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
availability:checkPerform availability checks
mandates:writeCreate or cancel a new payment mandate
mandates:readGet existing mandates
payments:writeCreate or cancel a new payment
payments:readGet existing payments
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
Test and Learn Projects
Next
Availability Check