Skip to navigation
Prefill API - Guide

Authorization

View as Markdown

All partner-facing Prefill APIs use OAuth 2.0 with the Client Credentials grant type. This is a system-to-system flow. No customer or browser redirect is involved. Your backend systems authenticate directly with Co‑operators using credentials issued during onboarding. 

Credentials

During onboarding, Co‑operators will issue:

  • client_id

  • client_secret

Store these credentials securely in a server-side secrets manager or equivalent credential store.

Do not expose credentials in:

  • Client-side code.

  • Browser or mobile requests.

  • URL parameters.

  • Application logs.

  • Analytics or monitoring payloads.

Credentials may expire or require renewal based on your partner agreement.

Requesting an Access Token

Before calling any Prefill API, your system must obtain a Bearer token. 

Endpoint: POST https://{{base_url}}/api/1.0/oauth2/access_token
Headers:
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)> 
Body:
grant_type=client_credentials

Example response:

{
  "access_token": "eyJhbGci...token",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Using the Token

Include the token in the Authorization header of every subsequent API call: 

Authorization: Bearer <access_token>

Token Lifecycle

Tokens expire after 1 hour (3600 seconds). When a token expires, request a new one using the same client credentials flow. To avoid interruptions, implement token caching and pre-emptive renewal (e.g., renew when less than 5 minutes of lifetime remain rather than waiting for a 401 response). 

Security Requirements

  • All API traffic must use HTTPS/TLS. Unencrypted connections are rejected. 

  • Client secret must never appear in client-side code, browser requests, URL parameters, or application logs. 

  • Credentials are stored encrypted server-side and only decrypted at the time of authentication. 

  • IP allow-listing may be required depending on your partner agreement. Confirm with your Co‑operators integration contact during onboarding.