Authentication

GameRamp API uses a secure two-step authentication process:

Generate HMAC-SHA256 signature using your API Secret
Exchange signature for JWT tokens via login endpoint

Authentication Flow

Generate Signature

Create HMAC-SHA256 signature with your API Secret

Send signature to /auth/login endpoint

Receive Tokens

Get JWT access token and refresh token

Authenticate Requests

Use Bearer token in Authorization header

Generating the Signature

The signature authenticates your API requests using HMAC-SHA256.

Signature Components

Create a pipe-delimited string with three values:

apiKey|deviceId|timestamp

Example:

test_tenant_4Dqms3ygG9FVC|device-123|2025-07-15T19:43:41Z

Signature Generation Steps

Node.js
Python
C# / Unity

const crypto = require('crypto');

function generateSignature(apiKey, deviceId, timestamp, apiSecret) {
  // Create the payload
  const payload = `${apiKey}|${deviceId}|${timestamp}`;

  // Generate HMAC-SHA256
  const hmac = crypto.createHmac('sha256', apiSecret);
  hmac.update(payload);

  // Return Base64 encoded signature
  return hmac.digest('base64');
}

// Example usage
const apiKey = 'test_tenant_4Dqms3ygG9FVC';
const deviceId = 'device-123';
const timestamp = new Date().toISOString();
const apiSecret = 'your-api-secret';

const signature = generateSignature(apiKey, deviceId, timestamp, apiSecret);

Once you have the signature, make a login request:

curl -X POST 'https://api.gameramp.com/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "test_tenant_4Dqms3ygG9FVC",
    "deviceId": "device-123",
    "timestamp": "2025-07-15T19:44:26Z",
    "signature": "/Sn9msNKK4ifTEYrGC/GKpRptolLIyWi4jsfdn5S4g8="
  }'

Request Body

apiKey

string

required

Your API Key provided by GameRamp

deviceId

string

required

Unique device identifier from client

timestamp

string

required

Current UTC timestamp in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ)

signature

string

required

HMAC-SHA256 signature encoded in Base64

Response

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "userId": "device-123_unique_id",
  "deviceId": "device-123",
  "gameId": "default_game",
  "tenantId": "test_tenant_1752523421",
  "playerConfig": {
    "playerStatus": {
      "isPayer": {
        "value": true,
        "defaultValue": false,
        "expiredAt": null
      }
    },
    "storeConfig": {
      "activeSkus": [...]
    }
  }
}

Using the JWT Token

After successful authentication, include the JWT token in all API requests:

curl -X GET 'https://api.gameramp.com/v1/player/status' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'X-Tenant-ID: your-tenant-id' \
  -H 'X-Game-Id: your-game-id'

Required Headers

All authenticated endpoints require:

Authorization

string

required

Bearer token obtained from login

Authorization: Bearer <accessToken>

Content-Type

string

Set to application/json for JSON payloads

X-Tenant-ID

string

Your tenant identifier

X-Game-Id

string

Your game identifier

Token Refresh

Access tokens expire after the duration specified in expiresIn. Use the refresh token to obtain new tokens:

curl -X POST 'https://api.gameramp.com/auth/refresh' \
  -H 'Content-Type: application/json' \
  -d '{
    "refreshToken": "your-refresh-token"
  }'

See Refresh Token endpoint for details.

Security Requirements

Keep your API Secret secure and never expose it in client-side code or public repositories.

Timestamp Validation

Timestamps must be within 5 minutes of server time
Use UTC time in ISO 8601 format
Format: YYYY-MM-DDThh:mm:ssZ

Best Practices

Secure Storage

Store API Secret in secure environment variables or key management systems

Server-Side Only

Generate signatures on your backend server, never in client applications

Token Management

Implement automatic token refresh before expiration

Error Handling

Handle 401 errors by refreshing tokens or re-authenticating

Error Responses

401 Unauthorized

Invalid signature or expired token

{
  "error": "Invalid authentication credentials"
}

400 Bad Request

Timestamp outside acceptable window (±5 minutes)

{
  "error": "Request timestamp is outside the acceptable time window"
}

Testing

Use these development credentials for testing:

Test credentials only work in development environment.

{
  "apiKey": "test_tenant_4Dqms3ygG9FVC",
  "apiSecret": "b815ebac-9744-43db-b5e6-89f90620297e-Wjl8qlWrJn2r4OEB7UXJ_L8iYOLTR8p10t83Wi_79Q"
}

Getting Started

Authentication

Events

Player

Authentication

Authentication

Authentication Flow

Generating the Signature

Signature Components

Signature Generation Steps

Request Body

Response

Using the JWT Token

Required Headers

Token Refresh

Security Requirements

Timestamp Validation

Best Practices

Error Responses

401 Unauthorized

400 Bad Request

Testing

Next Steps

Login Endpoint

Events API

Getting Started

Authentication

Events

Player

​Authentication

​Authentication Flow

​Generating the Signature

​Signature Components

​Signature Generation Steps

​Login Request

​Request Body

​Response

​Using the JWT Token

​Required Headers

​Token Refresh

​Security Requirements

​Timestamp Validation

​Best Practices

​Error Responses

​401 Unauthorized

​400 Bad Request

​Testing

​Next Steps

Login Endpoint

Events API

Authentication

Authentication Flow

Generating the Signature

Signature Components

Signature Generation Steps

Login Request

Request Body

Response

Using the JWT Token

Required Headers

Token Refresh

Security Requirements

Timestamp Validation

Best Practices

Error Responses

401 Unauthorized

400 Bad Request

Testing

Next Steps