Authentication Overview

The myPOS API Gateway uses a dual-authentication mechanism combining OAuth2 Bearer tokens and Session IDs to secure all API endpoints. This approach ensures both partner authentication and merchant authorization for every request.

Prerequisites

1. Partner Integration Setup

Partners must first create an Integration in the myPOS Partner Portal. Each integration receives unique credentials:

2. Merchant Approval

After a merchant approves your integration, you'll receive merchant-specific credentials that establish the relationship between your integration and that particular merchant:

Authentication Flow

Every API Gateway request requires four headers to authenticate and authorize your requests:

Step 1: Generate OAuth2 Bearer Token

Use your integration credentials to obtain a Bearer token:

curl --request POST \
  --url https://demo-api-gateway.mypos.com/api/v1/oauth/token \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode client_id=client_95b0d079f395435aaf34dda1d9738b37 \
  --data-urlencode client_secret=secret_66e8622ab22cbff78bc3dc519f26c53b4216ed7839dd3f034b1692addf3dc8d6 \
  --data-urlencode grant_type=client_credentials

Response:

{
  "access_token": "20002A6F33C5277D98DC00A6E0493AEFE3F99823E62DFA9AAFB1D2F952420F3B-1",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "accounting.read accounting.write banking.read banking.write"
}

Step 2: Create Session ID

Use your merchant-specific credentials and the Bearer token from Step 1 to obtain a Session ID:

curl --request POST \
  --url https://demo-api-gateway.mypos.com/api/v1/auth/session \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 20002A6F33C5277D98DC00A6E0493AEFE3F99823E62DFA9AAFB1D2F952420F3B-1' \
  --header 'Content-Type: application/json' \
  --data '{
  "client_id": "cli_3nVKcNDxzBLHmC59HDhbcHnX4LxT",
  "client_secret": "sec_jQ6voJKujLr5zqeYtORcb0JsiQKdqz4F3U9GIZhDSQ0GpF4eK8WlJGg14qAP"
}'

Response:

{
  "session": "77444f76971e41268bc7d2804b31c73f",
  "expires_in": 3600
}

Step 3: Make Authenticated API Requests

Include all four headers in every API Gateway request:

curl --request POST \
  --url https://demo-api-gateway.mypos.com/epos/v1/payments \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json; x-api-version=1' \
  --header 'Authorization: Bearer 20002A6F33C5277D98DC00A6E0493AEFE3F99823E62DFA9AAFB1D2F952420F3B-1' \
  --header 'X-Application-Id: mps-app-30000338' \
  --header 'X-Partner-Id: mps-p-10000152' \
  --header 'X-Session: 77444f76971e41268bc7d2804b31c73f' \
  --data '{
  ...
}'

Generate OAuth2 Bearer Token

The OAuth2 token endpoint authenticates your partner integration with the API Gateway using the Client Credentials grant type. This token proves your identity as a registered partner.

Endpoint: POST /api/v1/oauth/token

Key Characteristics:

• Use your integration credentials (client_id and client_secret from the Partner Portal)
• Credentials must be submitted in URL-encoded format (application/x-www-form-urlencoded)
• Returns a Bearer token with scope-based permissions (e.g., accounting.read, banking.write)
• The token expires after the time specified in expires_in (typically 3600 seconds / 1 hour)
• Include the token in the Authorization: Bearer <token> header for all subsequent API requests

Required Parameters:

• client_id: Your integration's client ID
• client_secret: Your integration's client secret
• grant_type: Must be set to client_credentials

Create Session for Merchant

The session endpoint establishes a connection between your integration and a specific merchant. This confirms that the merchant has authorized your integration to access their data.

Endpoint: POST /api/v1/auth/session

Key Characteristics:

• Requires the Bearer token from the OAuth2 endpoint in the Authorization header
• Use your merchant-specific credentials (received after merchant approval) in the request body
• Credentials must be submitted as JSON in the request body
• Returns a session token that identifies the integration-merchant relationship
• The session token must be included in the X-Session header for all API requests
• Sessions expire after the time specified in expires_in (typically 360 seconds / 5 minutes)
• Security: Three consecutive failed authentication attempts will lock the account

Required Headers:

• Authorization: Bearer <token>: The OAuth2 token from Step 1

Required Parameters:

• client_id: The merchant-specific client ID (format: cli_*)
• client_secret: The merchant-specific client secret (format: sec_*)

Authentication Flow Diagram

The diagram below illustrates the complete authentication flow for the myPOS API Gateway: