Skip to main content
Keystone uses two authentication modes for integrations.

​
Credentials issued by Keystone

Keystone issues two values for an integration.
CredentialUsed asWhere to use it
API key<api_key>x-api-key header on catalog requests
Integration ID<integration_id>partnerId during OTP verification and x-partner-id on commerce requests
Usage terms:
  • Keep the API key on your server. Do not expose it in mobile apps, browser clients, logs, analytics tools, or public repositories.
  • Treat the API key as a secret. Ask Keystone to rotate it immediately if it is exposed.
  • Use the API key only for catalog reads: categories, products, product detail, and search.
  • Do not send partnerId on catalog requests. The API key already identifies which catalog to return.
  • Use the integration ID only where the API explicitly asks for partnerId or x-partner-id.
  • Customer access tokens are user-specific. Do not share one customer’s token with another customer or background job.

​
API key

Catalog endpoints use the API key issued by Keystone in the x-api-key header. 
x-api-key: <api_key>
The API key identifies which catalog to return. Do not send partnerId in catalog URLs, query params, or request bodies. Keep this key server-side. Do not ship it in mobile apps or browser clients.

​
Customer JWT

Customer endpoints use a bearer token. Checkout, wallet, support, and return requests also require x-partner-id. 
Authorization: Bearer <access_token>
x-partner-id: <integration_id>
The customer token is issued after OTP verification. Send x-partner-id on requests that create or read commerce data, using the integration ID issued by Keystone.

​
Send OTP

MethodEndpointAuth
POST/auth/otp/sendNone
Request: 
curl -X POST https://dev-api.keystonecommerce.in/api/v1/auth/otp/send \
  -H "Content-Type: application/json" \
  -d '{"phone":"<customer_phone>"}'
Body: 
{
  "phone": "<customer_phone>"
}
Response: 
{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "message": "OTP sent successfully",
    "expiresIn": 300
  }
}

​
Verify OTP

MethodEndpointAuth
POST/auth/otp/verify?partnerId={partnerId}None
partnerId is required when registering a new customer. Use the integration ID issued by Keystone. Request: 
curl -X POST "https://dev-api.keystonecommerce.in/api/v1/auth/otp/verify?partnerId=<integration_id>" \
  -H "Content-Type: application/json" \
  -d '{"phone":"<customer_phone>","code":"123456"}'
Body: 
{
  "phone": "<customer_phone>",
  "code": "123456"
}
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": "<integration_id>"
    }
  }
}

​
Refresh token

MethodEndpointAuth
POST/auth/refreshNone
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

MethodEndpointAuth
POST/auth/logoutBearer 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"
  }
}