How to

Log in user

Authenticate users and obtain Bearer tokens for Geins Merchant API access using Geins Auth Service

Prerequisites

Geins account name
Merchant API key
Customer credentials (username/email and password)

Goal

Authenticate user credentials securely
Obtain Bearer token for Merchant API requests

Architecture at a glance

Send username → get signature challenge → send signed credentials → receive Bearer token
Use token in Authorization: Bearer {token} header for Merchant API calls

APIs used

Auth Service: https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod/login
Merchant API: https://merchantapi.geins.io/auth/sign/{MERCHANT_API_KEY}

You can find your ACCOUNT_NAME when you log in to your account. Note that the account name in the auth URL is always followed by _prod.

Important: All calls to the auth service must be handled from the server-side to prevent CORS issues. Do not make direct calls to the auth service from client-side code.

Step-by-step

Start authentication challenge

Send the username to get a signature challenge:

Request example

curl -X POST "https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "{USER_EMAIL}"
  }'

// Note: This code should run on the server-side to prevent CORS issues
const authUrl = `https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod/login`;

const challengeResponse = await fetch(authUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ username: '{USER_EMAIL}' })
});

const challengeData = await challengeResponse.json();

Response example

200 OK

response.json

{
  "sign": "IDENTITY_SIGN_STRING"
}

Get signature from Merchant API

Use the signature challenge from step 1 (IDENTITY_SIGN_STRING) to get the signed identity:

Request example

curl -X GET "https://merchantapi.geins.io/auth/sign/{MERCHANT_API_KEY}?identity={IDENTITY_SIGN_STRING}" \
  -H "Cache-Control: no-cache"

const params = new URLSearchParams({ identity: 'IDENTITY_SIGN_STRING' });
const signUrl = `https://merchantapi.geins.io/auth/sign/{MERCHANT_API_KEY}?${params}`;

const signResponse = await fetch(signUrl, {
  method: 'GET',
  cache: 'no-cache'
});

const signature = await signResponse.json();

Response example

200 OK

response.json

{
  "identity": "IDENTITY_SIGN_STRING",
  "timestamp": "TIMESTAMP_STRING",
  "signature": "SIGNATURE_STRING"
}

Complete authentication

Send the signed credentials to complete login:

Request example

curl -X POST "https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "{USER_EMAIL}",
    "password": "{USER_PASSWORD}",
    "signature": {
      "identity": "IDENTITY_SIGN_STRING",
      "timestamp": "TIMESTAMP_STRING",
      "signature": "SIGNATURE_STRING"
    }
  }'

// Note: This code should run on the server-side to prevent CORS issues
const authUrl = `https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod/login`;

const authResponse = await fetch(authUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    username: '{USER_EMAIL}',
    password: '{USER_PASSWORD}',
    signature: {
      identity: "ID_STRING",
      timestamp: "TIMESTAMP_STRING",
      signature: "SIGNATURE_STRING"
    }
  })
});

const authData = await authResponse.json();

Response example

200 OK

response.json

{
  "token": "JWT_BEARER_TOKEN",
  "maxAge": 900
}

Use token with Merchant API

Include the Bearer token in Merchant API requests:

Request example

curl -X POST "https://merchantapi.geins.io/graphql" \
  -H "Content-Type: application/json" \
  -H "X-ApiKey: {MERCHANT_API_KEY}" \
  -H "Authorization: Bearer {JWT_BEARER_TOKEN}" \
  -d '{
    "query": "query { ... }"
  }'

const merchantResponse = await fetch('https://merchantapi.geins.io/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-ApiKey': '{MERCHANT_API_KEY}',
    'Authorization': `Bearer {JWT_BEARER_TOKEN}`
  },
  body: JSON.stringify({
    query: `query { ... }`
  })
});

Security and access

Always use HTTPS for authentication requests.
The Bearer token expires after 15 minutes, implement refresh logic as needed.
The signature-based flow prevents credential exposure and replay attacks.

Common pitfalls

Not handling the two-step flow properly—both requests to the auth endpoint are required.

Full authentication guide: Authentication flow

Handle product reviews

Submit and fetch product reviews using Geins Merchant API

Log out user

Securely log out users and invalidate authentication tokens using Geins Auth Service