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.

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": 86400,
      "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