How to

Reset user password

Complete password reset flow for users using Geins Merchant API

Prerequisites

Merchant API key
Geins transactional emails configured
Account url set up in Geins system

Goal

Allow users to reset their forgotten password through a secure email flow

Architecture at a glance

User requests reset → Email sent with reset link → User sets new password → Password updated

APIs used

Merchant API: https://merchantapi.geins.io/graphql

Step-by-step

Request password reset

Use the requestPasswordReset mutation to initiate the password reset process. This will send an email to the user with a password reset link:

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

Request example

mutation requestPasswordReset(
  $email: String!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  requestPasswordReset(
    email: $email
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  )
}

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

{
  "email": "{USER_EMAIL}",
  "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}" \
  -d '{"query":"mutation requestPasswordReset($email: String!, $channelId: String, $languageId: String, $marketId: String) { requestPasswordReset(email: $email, channelId: $channelId, languageId: $languageId, marketId: $marketId) }","variables":{"email":"{USER_EMAIL}","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": {
    "requestPasswordReset": true
  }
}

The mutation returns true regardless of whether the email exists in the system. This is a security measure to prevent email enumeration attacks.

Email with reset link

After the request is made, the user will receive an email containing a password reset link. The link should direct users to your password reset page with the reset key as a URL parameter:

https://yoursite.com/reset-password?key={RESET_KEY}

Commit password reset

Use the commitReset mutation to complete the password reset with the reset key and new password provided by the user.

Request example

mutation commitReset(
  $resetKey: String!
  $password: String!
  $channelId: String
  $languageId: String
  $marketId: String
) {
  commitReset(
    resetKey: $resetKey
    password: $password
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  )
}

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

{
  "resetKey": "{RESET_KEY}",
  "password": "NewSecurePassword123!",
  "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}" \
  -d '{"query":"mutation commitReset($resetKey: String!, $password: String!, $channelId: String, $languageId: String, $marketId: String) { commitReset(resetKey: $resetKey, password: $password, channelId: $channelId, languageId: $languageId, marketId: $marketId) }","variables":{"resetKey":"{RESET_KEY}","password":"NewSecurePassword123!","channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'

Response example

200 OK

response.json

{
  "data": {
    "commitReset": true
  }
}

Multi-market support

Both mutations support optional parameters for multi-market configurations:

Read more about channelId, languageId, and marketId in the multi-market support guide.

Common pitfalls

Invalid or expired reset key - keys expire after a set period
Using the same reset key twice - each key can only be used once

Security considerations

Always use HTTPS for password reset pages
Clear any active sessions when password is reset

Search products

Search products using text search and sort by relevance with Geins Merchant API