How to

Register user

Prerequisites

Geins account name
Merchant API key

Goal

Register new user in auth service
Register user in Merchant API
Obtain Bearer token for authenticated API access

Architecture at a glance

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

APIs used

Auth Service: https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod/register
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 registration challenge

Send the desired username/email to get a signature challenge:

Request example

curl -X POST "https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod/register" \
  -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/register`;

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 registration

Send the signed credentials along with user information to complete registration:

Request example

curl -X POST "https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod/register" \
  -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/register`;

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

const registrationData = await registrationResponse.json();

Response example

200 OK

response.json

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

Register user in Merchant API

To be able to use the token with the Merchant API to place orders and manage user data, you must first register the user in the Merchant API.

Try it out in the GraphQL Playground using the query, headers and variables below.

Request example

mutation updateUser(
  $user: UserInputType!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  updateUser(
    user: $user
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  ) {
    email
  }
}

{
  "Accept": "application/json",
  "X-ApiKey": "{MERCHANT_API_KEY}",
  "Authorization": "Bearer {JWT_BEARER_TOKEN}"
}

// To register a user without any additional data, leave the user object empty
{ 
  "user": {},
  "channelId": "{CHANNEL_ID}",
  "languageId": "{LANGUAGE_ID}",
  "marketId": "{MARKET_ID}"
}

curl -X POST https://merchantapi.geins.io/graphql \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-ApiKey: {MERCHANT_API_KEY}" \
  -H "Authorization: Bearer {JWT_BEARER_TOKEN}" \
  -d '{"query":"mutation updateUser($user: UserInputType!, $channelId: String, $languageId: String, $marketId: String) { updateUser(user: $user, channelId: $channelId, languageId: $languageId, marketId: $marketId) { email } }","variables":{"user":{},"channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'

The channelId, languageId, and marketId arguments are optional and can be left out to use default values.

Response example

200 OK

response.json

{
  "data": {
    "updateUser": {
      "email": "{USER_EMAIL}"
    }
  }
}

Use the token for authenticated Merchant API calls

The user is now registered and you can use the obtained Bearer token to make authenticated requests to the Merchant API by always including it in the Authorization header:

headers.json

{
  ...
  "Authorization": "Bearer {JWT_BEARER_TOKEN}"
  ...
}

Update user data

How to: Update a user →

Learn more what options you can provide in the user object when updating user data in the Merchant API.

Registration validation

Username requirements: Must be a valid email address
Duplicate accounts: Registration will fail if username already exists

Security and access

Always use HTTPS for registration requests
The Bearer token expires after 15 minutes, implement refresh logic as needed

Common pitfalls

Not handling the two-step flow properly—both requests to the register endpoint are required
Missing refresh token extraction from response headers

Login guide: Log in as user
Token refresh guide: Refresh user token
Full authentication guide: Authentication flow

Refresh user token

Refresh the Bearer token for Geins Merchant API access using Geins Auth Service

Reset user password

Complete password reset flow for users using Geins Merchant API