Authentication - Keystone Commerce API Docs

Use these terms throughout the API documentation.

Credentials and identifiers

Term	Placeholder	Where to use it
Partner API key	`<api_key>`	`x-api-key` header on catalog and exchange quote requests
Partner ID	`<partner_id>`	`partnerId` during OTP verification and `x-partner-id` on commerce requests
Customer access token	`<access_token>`	`Authorization` header on customer requests
Refresh token	`<refresh_token>`	Token refresh and logout request bodies

Partner API key

Send the Partner API key in the x-api-key header for categories, products, product detail, search, and exchange quotes.

x-api-key: <api_key>

The Partner API key identifies your catalog, so do not send a Partner ID on these requests. Keep the key server-side and out of logs and public repositories. Ask Keystone to rotate it if it is exposed.

Customer access token

OTP verification issues a Customer access token and Refresh token. Send the Customer access token using the Authorization header shown below. Checkout, wallet, support, and return requests also require 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.

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>",
    "user": {
      "id": "cmr928qjc000002s6nh2ufmo2",
      "phone": "<customer_phone>",
      "name": "<customer_name>",
      "email": "<customer_email>",
      "role": "USER",
      "partnerId": "<partner_id>"
    }
  }
}

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>"
  }
}

Logout

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

​Customer access token

​Send OTP

​Verify OTP

​Refresh token

​Logout

Credentials and identifiers

Partner API key

Customer access token

Send OTP

Verify OTP

Refresh token

Logout