Authentication

API Authentication

Jeel APIs follows OAuth 2.1 for API authentication and authorization. Client Credentials flow will be used to authenticate by providing the authorization server with client id and secret to obtain a token for API usage.

The diagram below explains the flow

A sample HTTP request to get an access token

POST https://auth.sandbox.jeel.co/oauth2/token

replace https://auth.sandbox.jeel.co with https://auth.jeel.co when using production

Headers

Name	Value
Content-Type	multipart/form-data

Body

multipart form

Name	Type	Description
client_id	string	Client id provided by Jeel Pay
client_secret	string	Client secret provided by Jeel Pay
grant_type	string	Always client_credentials

Response

200

{
  "access_token": "eyJraWQiOiJkMWZhOWEwOS0....",
  "token_type": "Bearer",
  "expires_in": 1991
}

Best Practices

⚠️ Important: The authentication endpoints are rate-limited. You must implement proper token caching to avoid hitting rate limits.

Always reuse valid tokens. Do not request a new token for every API call. Instead, store the access token after the first authentication and reuse it for subsequent requests until it expires.

Implementation Guidelines

Your authentication implementation should follow this caching logic:

1. Check for stored token - First, check if you have a previously saved access token in your cache/storage

2. Authenticate if no token exists - If no token is found, make an authentication request to obtain a new token

3. Store the token - Save the access_token and calculate the expiration timestamp using expires_in

4. Validate token expiration - Before using a stored token, verify it hasn't expired

5. Re-authenticate if expired - If the token is expired, request a new one and update your storage

6. Use valid cached token - If the token is still valid, use it for your API requests

Token Storage Considerations

• Store the access token securely

• Calculate and store the expiration timestamp: current_time + expires_in

• The expires_in value is in seconds

• Consider refreshing the token slightly before it expires to avoid edge cases (30 seconds is sufficient)

Example Workflow

Response Body

Parameter	Type	Description
access_token	string	JWT access token for API authentication
token_type	string	Token type (always "Bearer")
expires_in	integer	Token validity duration in seconds

Security Notes

• Never expose your client_id and client_secret in client-side code

• Store credentials securely using environment variables or secret management systems

• Use HTTPS for all authentication requests

• Implement proper error handling for authentication failures