Skip to main content

​
Overview

All e-CROSS APIs are private and require authentication. You must authenticate through the Generate Token API using your client credentials to generate an access token.
You cannot register yourself. Your e-CROSS representative must register your merchant user and provide you with clientId and clientSecret credentials.

​
Obtaining Credentials

Contact your e-CROSS representative to:
  1. Register your merchant account
  2. Obtain your clientId and clientSecret
  3. Receive your carrierId (used to send fulfillment events, if that applies to your use case)
These credentials are unique to your merchant account and should be kept secure. Never expose them publicly or commit them to version control.

​
Authentication Flow

  1. Request token: Use your clientId and clientSecret to obtain an access token via the Generate Token API
  2. Cache token: Store the token securely and reuse it until it expires
  3. Use token: Include the token in the Authorization header of all API requests
  4. Request a new token: A few minutes before the token expires, request a new token (step 1)

​
Token Expiration

The generated access token has an 8-hour validity. You must request a new token before the current one expires, to avoid being blocked by the APIs. If you invoke an API after the token has expired, you will receive a 401 Unauthorized error.

​
Token Management Best Practices

Cache your tokens: The generated access token has an 8-hour validity by default. We strongly recommend caching the token in a secure local cache and reusing it while it hasn’t expired. This avoids HTTP 429 Too Many Requests errors that can occur when requesting new tokens for every single business request.

​
Security Considerations

  • Keep your client credentials (clientId and clientSecret) secure and never expose them publicly
  • Implement proper token management and storage mechanisms to protect sensitive information
  • Use secure storage for cached tokens
  • Never commit credentials or tokens to version control
  • Rotate credentials periodically if compromised