Authentication

The eCard REST API uses OAuth 2.0 Client Credentials flow for machine-to-machine authentication. Your server authenticates by exchanging your client credentials (client ID and secret) for a short-lived JWT access token, which you then include as a Bearer token in all subsequent API requests. The platform handles token validation internally—your integration simply needs to manage token acquisition and renewal.

Tokens are acquired and renewed from a single endpoint in all cases: https://platform.ecardsystems.com/api. This is true whether you are calling our sandbox or production instance, and it applies both during development and after certification. The returned token is scoped to your access level by ECS and is valid against both environments. The only thing that changes after certification is where you send your other API calls, never where you get your token.

Prerequisites

Before making API calls, you must complete a one-time registration process with eCard Systems. During onboarding, you'll receive:

• Client ID — Your application's public identifier
• Client Secret — Your application's private key (keep this secure)

Contact your eCard Systems integration representative to initiate this setup. (Self service coming soon via new portal)

Authentication Flow

Step 1: Request an Access Token

Exchange your client credentials for a short-lived access token.

Endpoint

POST https://platform.ecardsystems.com/api/reporting/v1/auth/token

Request Headers

Content-Type: application/json; charset=utf-8

Request Body

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "grant_type": "client_credentials"
}

Response

{
  "data": {
    "type": "oauth-token",
    "attributes": {
      "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIs...",
      "token_type": "Bearer",
      "expires_in": 7200,
      "scope": "read:reports read:transactions export:reports"
    }
  },
  "meta": {
    "timestamp": "2025-10-21T14:28:51.029Z",
    "request_id": "req-1761056930392-ueryszt",
    "version": "1.0.0"
  },
  "jsonapi": {
    "version": "1.0"
  }
}

Step 2: Call the API

Include the access token in the Authorization header for all API requests.

Request Format

GET https://platform.ecardsystems.com/api/transaction/v1/{endpoint}
Authorization: Bearer {access_token}
Content-Type: application/json

The API validates your token automatically and extracts the necessary identifiers to process your request.

Code Example

// Fetch an access token from the authentication endpoint
const getAccessToken = async () => {
  const response = await fetch(
    'https://platform.ecardsystems.com/api/reporting/v1/auth/token',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: process.env.ECARDS_CLIENT_ID,
        client_secret: process.env.ECARDS_CLIENT_SECRET,
        grant_type: 'client_credentials'
      })
    }
  );

  const result = await response.json();
  return result.data.attributes.access_token;
};

// Make an authenticated API call
const callAPI = async (endpoint) => {
  const token = await getAccessToken();

  const response = await fetch(
    `https://platform.ecardsystems.com/api/transaction/v1/${endpoint}`,
    {
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.json();
};

Token Management Best Practices

Cache your tokens — Access tokens are valid for the duration specified in expires_in. Cache the token and reuse it for multiple requests rather than requesting a new token for each API call.

Handle expiration gracefully — Implement token refresh logic that requests a new token before the current one expires, or handles 401 Unauthorized responses by fetching a fresh token and retrying.

Secure your credentials — Store your client_id and client_secret in environment variables or a secrets manager. Never expose them in client-side code or version control.

Error Responses