Authentication - Keystone Commerce API Docs

Keystone supports three ways to authenticate customer requests. Use Partner API key and External user ID for new integrations. Your backend authenticates the customer and calls Keystone on their behalf, so you do not manage customer access or refresh tokens.

Method	Use it when	Customer tokens
Partner API key and External user ID (recommended)	Your backend authenticates the customer and makes every customer request	None
Server-to-server session login (other methods)	Your app calls Keystone directly with a customer token issued through your backend	Access and refresh tokens
OTP login (other methods)	Keystone must verify the customer’s phone	Access and refresh tokens

Credentials and identifiers

Term	Placeholder	Where to use it
Partner API key	`<api_key>`	`x-api-key` header on every server-to-server request
External user ID	`<external_user_id>`	Stable customer identifier from your system, sent in `x-external-user-id` or in the provisioning request body
Partner ID	`<partner_id>`	`partnerId` during OTP verification and `x-partner-id` on token-based customer requests
Customer access token	`<access_token>`	`Authorization` header on token-based customer requests
Refresh token	`<refresh_token>`	Token refresh and logout request bodies

Partner API key

The Partner API key identifies your partner account. Send it in the x-api-key header.

x-api-key: <api_key>

Catalog, search, and exchange quote requests need only this header. Keystone derives your Partner ID from the key, so do not send a Partner ID with it. Keep the Partner API key on your backend. Do not place it in a mobile app, browser, logs, or public repository. Anyone holding the key can act as any of your customers, so ask Keystone to rotate it immediately if it is exposed.

Partner API key and External user ID

Use this method when your backend already authenticates the customer. Your backend sends the Partner API key and the customer’s External user ID on each request. Keystone resolves the customer and enforces ownership. No access or refresh tokens are issued. Ask Keystone to enable server authentication for your partner before using this method. Until it is enabled, provisioning and customer requests return 403.

Step 1: Provision the customer

Provision each customer once before making requests for them. Repeating the call for the same customer is safe and returns the same account.

Method	Endpoint	Auth
`POST`	`/partner/users/resolve`	Partner API key

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/partner/users/resolve \
  -H "x-api-key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "<external_user_id>",
    "phone": "<customer_phone>",
    "name": "<customer_name>"
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "user": {
      "id": "cmr928qjc000002s6nh2ufmo2",
      "name": "<customer_name>",
      "phone": "<customer_phone>"
    },
    "isNewUser": true,
    "externalUserId": "<external_user_id>"
  }
}

All three fields are required:

Field	Rules
`externalUserId`	1 to 128 characters, no whitespace. Use an ID that is unique within your system and never reassigned.
`phone`	Exactly 10 digits
`name`	2 to 100 characters, not blank

isNewUser is true when Keystone creates a customer. It is false when the customer already exists or when Keystone links an existing OTP customer with the same phone. Provisioning does not overwrite an existing customer profile. If the External user ID and phone do not match the existing identity, the API returns 409 instead of rebinding the account. Do not use a new External user ID to bypass this conflict. Contact Keystone before changing a customer identity mapping.

Step 2: Make customer requests

Send both headers on every customer request. Do not send Authorization or x-partner-id.

x-api-key: <api_key>
x-external-user-id: <external_user_id>

Request:

curl "https://dev-api.keystonecommerce.in/api/v1/orders?page=1&limit=5" \
  -H "x-api-key: <api_key>" \
  -H "x-external-user-id: <external_user_id>"

Name and phone are not required after provisioning. Request bodies, ownership checks, and x-idempotency-key rules are the same as for token-based requests. This method is supported on these endpoints:

Area	Endpoints
Profile	`/users/me`, `/users/me/terms-acceptance`
Addresses	`/users/me/addresses`
Orders	`/orders`, including checkout quotes, coupons, and invoices
Shipping	`/shipping/serviceability`
Wallet	`/wallet`, `/wallet/quote`
Payments	`/payments/orders/{orderId}/initiate`, `/payments/orders/{orderId}/abandon`
Delivery	`/delivery/quote`
Support	`/support/tickets`, `/support/uploads/signed-urls`
Returns	`/returns`, `/returns/uploads/signed-urls`

Referrals and promotion redemption do not support this method. Use a Customer access token for those endpoints.

Errors

Status	Cause
`401`	Missing or invalid Partner API key, invalid or unprovisioned External user ID, or `Authorization` sent together with `x-external-user-id`
`403`	Server authentication is not enabled for your partner, or the phone number belongs to a Keystone staff account (`This phone number belongs to a privileged account`)
`409`	Provisioning details conflict with an existing customer identity
`429`	A rate limit was exceeded

Unknown External user IDs never create a customer. Provision the customer first.

Other authentication methods

Use these methods when your app must hold a customer token and call Keystone directly. Both methods issue a Customer access token and Refresh token. Send the Customer access token in the Authorization header. Every token-based customer request except profile, address, and upload URL requests also requires x-partner-id.

Authorization: Bearer <access_token>
x-partner-id: <partner_id>

Use each Customer access token only for the customer account that received it.

Use server-to-server session login when your backend authenticates the customer and your app needs its own customer token. The endpoint creates the customer when needed or logs in the existing customer. It shares the External user ID mapping with the Partner API key and External user ID method.Server authentication must be enabled for your partner. A valid Partner API key returns 403 until it is enabled.Create a session

Method	Endpoint	Auth
`POST`	`/partner/auth/session`	Partner API key

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/partner/auth/session \
  -H "x-api-key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "<external_user_id>",
    "phone": "<customer_phone>",
    "name": "<customer_name>"
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "accessToken": "<access_token>",
    "refreshToken": "<refresh_token>",
    "accessTokenExpiresAt": "2026-10-01T11:00:00.000Z",
    "refreshTokenExpiresAt": "2026-10-31T10:00:00.000Z",
    "user": {
      "id": "cmr928qjc000002s6nh2ufmo2",
      "name": "<customer_name>",
      "phone": "<customer_phone>"
    },
    "isNewUser": true
  }
}

The request body follows the same rules as provisioning, including the 409 identity conflict. Access tokens from this endpoint last one hour. Refresh tokens last 30 days. Send the returned tokens only to the authenticated customer over a secure connection.Revoke a customer’s sessionsRevoke every access and refresh token for a customer, for example when they sign out on all devices or their account is compromised.

Method	Endpoint	Auth
`POST`	`/partner/auth/revoke`	Partner API key

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/partner/auth/revoke \
  -H "x-api-key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"externalUserId":"<external_user_id>"}'

The endpoint returns 204 with no body, including for unknown External user IDs. It returns 401 if server authentication is not enabled for your partner.Session creation and revocation share the provisioning rate limits: 10 per minute per External user ID and 600 per minute per partner.

Use OTP login when Keystone must verify the customer’s phone.Send OTP

Method	Endpoint	Auth
`POST`	`/auth/otp/send`	None

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/auth/otp/send \
  -H "Content-Type: application/json" \
  -d '{"phone":"<customer_phone>"}'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "message": "OTP sent successfully",
    "expiresIn": 300
  }
}

Verify OTP

Method	Endpoint	Auth
`POST`	`/auth/otp/verify?partnerId={partnerId}`	None

partnerId is required for every customer OTP verification. Use the Partner ID issued for your integration. Send referralCode only when the customer signs up with a referral code.Request:

curl -X POST "https://dev-api.keystonecommerce.in/api/v1/auth/otp/verify?partnerId=<partner_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "<customer_phone>",
    "code": "123456",
    "referralCode": "<referral_code>"
  }'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "accessToken": "<access_token>",
    "refreshToken": "<refresh_token>",
    "accessTokenExpiresAt": "2026-10-02T10:00:00.000Z",
    "refreshTokenExpiresAt": "2026-10-31T10:00:00.000Z",
    "user": {
      "id": "cmr928qjc000002s6nh2ufmo2",
      "phone": "<customer_phone>",
      "name": "<customer_name>",
      "email": "<customer_email>",
      "role": "USER",
      "partnerId": "<partner_id>"
    }
  }
}

OTP send allows 3 requests per phone number per minute, and 5 per minute from one IP address. OTP verify allows 5 requests per minute.

Refresh and log out

These endpoints apply to tokens from both server-to-server session login and OTP login.Refresh token

Method	Endpoint	Auth
`POST`	`/auth/refresh`	None

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"<refresh_token>"}'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "accessToken": "<new_access_token>",
    "refreshToken": "<new_refresh_token>",
    "accessTokenExpiresAt": "2026-10-01T11:00:00.000Z",
    "refreshTokenExpiresAt": "2026-10-31T10:00:00.000Z"
  }
}

A refreshed access token has the same lifetime as the login that issued it: one hour for server-to-server session login.Each Refresh token works once. Replace both stored tokens with the new pair, and send only one refresh request at a time per customer.If a used Refresh token is sent again within 60 seconds, the API returns 401 and the new pair stays valid. If it is sent again later, Keystone treats it as stolen and revokes every session for that customer. Create a new session to recover.Refresh allows 20 requests per minute per customer and 600 per minute per partner.Log outLogout revokes only the Refresh token you send. To revoke every session for a customer, use POST /partner/auth/revoke.

Method	Endpoint	Auth
`POST`	`/auth/logout`	Customer access token

Request:

curl -X POST https://dev-api.keystonecommerce.in/api/v1/auth/logout \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"<refresh_token>"}'

Response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "message": "Logged out successfully"
  }
}

​Credentials and identifiers

​Partner API key

​Partner API key and External user ID

​Step 1: Provision the customer

​Step 2: Make customer requests

​Errors

​Other authentication methods

Credentials and identifiers

Partner API key

Partner API key and External user ID

Step 1: Provision the customer

Step 2: Make customer requests

Errors

Other authentication methods