Skip to content

Auth

Application

application is the basic unit of api integration. Store admin will create application with relevant details and share the application developer with client_id and client_secret

Authentication Process

sequenceDiagram
  autonumber
  App->>Server: call send otp api - (inputs: phone number or email)
  Server->>App: respond with verification token
  App->>Server: call token api (inputs" otp value & verification token)
  Server->>App: respond with access token
sequenceDiagram
  autonumber
  App->>Server: login with email/password
  Note right of Server: sends otp to second factor phone
  Server->>App: respond with verification token
  App->>Server: call token api (inputs" otp value & verification token)
  Server->>App: respond with access token

For server to server app, initial access token is generated by store admin and shared with developer.

API

Objects

Verification Token Object
Field Data Type Description
token string token string, will be null when response code is not 200
error string error message, will be null when response code is 200
Access Token Object
Field Data Type Description
access_token string bearer token that should be sent for subsequent requests.
token_type string type of the token, it will always be Bearer.
created integer value in epoch seconds, when the token is created.
expires_in integer value in seconds, token will no longer be valid after when current epoch > created_at + expired_in.
refresh_token string token to be used in refresh_token grant when the current token expires.

Login

POST /api/platform/v1/login

This api responds with verification token object that can be used in access token api. Additionally this api also ensures that an otp is sent to staff's phone number.

Request Body
Field Data Type Description Required
email string Email of the Staff
password string Password of the Staff 
{
  "email": "string",
  "password": "string"
}
curl command 
curl 'http://localhost:3000/api/platform/v1/login' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic YTlmN2VmMjA6QW9vT2JBdGRCNUNMUXA5bE9pRHNGbG9QMjVLcGdUYnJiZGhCRV9DWExwaw==' \
  -H 'Content-Type: application/json' \
  --data-raw '{"email":"staff@apexcommerce.com","password":"password"}'
Response Body

Data object received is verification token

Success
{
  "status": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2ODA2Njc3MzMsImlkIjoiYzU5YWFmZWYtNzJjMC00OGVkLWJjOGQtNzY0YmJjMjg1YjU4IiwianRpIjoiZTA5ZTlmNzctYjc2NS00NzdkLTk0YzctODdjNmRjNjc4YzU2IiwiaWF0IjoxNjgwNjY3MTMzLCJzdWIiOiJzdGFmZiJ9.DIh5DD9kb7A3zulSo3Wmuxp0Q6C6awHp8LX0DlgNQ7E",
    "error": null
  }
}
Failure
{
  "status": "failure",
  "data": {
    "token": null,
    "error": "some error message"
  }
}

Retrieve Access Token

POST /api/platform/v1/token

This api responds with with access token object that can be used in Bearer authentication for future api calls, api clients must persist this information and check for expiry before making authenticated api calls.

Request Body
Field Data Type Description Required
grant_type string Fixed value password
username string token received in login api
password string otp received on second factor phone 
{
  "grant_type": "password",
  "password": "otp",
  "username": "token"
}
curl command 
curl 'http://localhost:3000/api/platform/v1/token' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic YTlmN2VmMjA6QW9vT2JBdGRCNUNMUXA5bE9pRHNGbG9QMjVLcGdUYnJiZGhCRV9DWExwaw==' \
  -H 'Content-Type: application/json' \
  --data-raw '{"username":"eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2ODA3NzAyMzEsImlkIjoiZWM3ZWI2OGYtMGRlYi00Y2M3LWE5MmQtMTQ2OGUyYzNjNTU0IiwianRpIjoiNTY4NmU0ZTgtMWMzOS00MzFmLWJjZTYtNGM2OTkxODFiYjBmIiwiaWF0IjoxNjgwNzY5NjMxLCJzdWIiOiJzdGFmZiJ9.RRjLAFQMjLPiXHUphK1TaX_qs64M5J8WGIxY-zABDVk","password":"100100","grant_type":"password"}'
Response Body

response json is access token object

Success
{
  "access_token": "bgcELuHgoVxBqrdiVNne0WxBLsV9Fk45Y1ZsTRW_L1s",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "1DY2Lds8KU97IJF63PpaN_A8ucuDDSHaDOT6Y7b_lrQ",
  "created_at": 1680667245
}
Field Data Type Description
error string error code.
error_description string detailed explanation of what could have gone wrong.
Failure
{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}

Refresh Access Token

POST /api/platform/v1/token

This api provides mechanism to exchange a new access token for an expired one. If this api fails with 401 errors, it is recommended for api client to start authentication process from beginning.

Request Body
Field Data Type Description Required
grant_type string Fixed value password
refresh_token string refresh_token received in access token request 
  {
    "grant_type": "refresh_token",
    "refresh_token": "token"
  }
curl command 
curl 'http://localhost:3000/api/platform/v1/token' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic YTlmN2VmMjA6QW9vT2JBdGRCNUNMUXA5bE9pRHNGbG9QMjVLcGdUYnJiZGhCRV9DWExwaw==' \
  -H 'Content-Type: application/json' \
  --data-raw '{"grant_type":"refresh_token", "refresh_token":"iWaTHakJEB18WtrS1h9Q0wmVw1FLFA1S4LBiVywtlHg"}'
Response Body

Same response body as mentioned in retrieve access token api

Revoke Access Token

POST /api/platform/v1/token/revoke

Revoking access token is equivalent to performing logout on behalf of user.

Request Body
Field Data Type Description Required
token string access token 
{
  "token": "string"
}
curl command 
curl 'http://localhost:3000/api/platform/v1/token/revoke' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic YTlmN2VmMjA6QW9vT2JBdGRCNUNMUXA5bE9pRHNGbG9QMjVLcGdUYnJiZGhCRV9DWExwaw==' \
  -H 'Content-Type: application/json' \
  --data-raw '{"token":"iDJYbofANxyB5w4iwDW1nrmlTdiKsNAkLHpBHQkUlX4"}'
Response Body

Response is always an empty json {}

Resend OTP

POST /api/platform/v1/login

Sometimes user may not receive the otp on their phone due to various issues related to phone network, in such cases api client can request another attempt to send the otp.

Request Body
Field Data Type Description Required
email string Email of the Staff used in the login call
token string Verification token received during login call 
{
  "email": "string",
  "token": "string"
}
curl command 
curl 'http://localhost:3000/api/platform/v1/login/resend_otp' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic YTlmN2VmMjA6QW9vT2JBdGRCNUNMUXA5bE9pRHNGbG9QMjVLcGdUYnJiZGhCRV9DWExwaw==' \
  -H 'Content-Type: application/json' \
  --data-raw '{"email":"staff@apexcommerce.com","token":"eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2ODA3NzEyMTIsImlkIjoiZWM3ZWI2OGYtMGRlYi00Y2M3LWE5MmQtMTQ2OGUyYzNjNTU0IiwianRpIjoiYjhiOTJkYjgtZmY1OS00YzdkLWJiZGQtZTFiZmI1NThiYmYxIiwiaWF0IjoxNjgwNzcwNjEyLCJzdWIiOiJzdGFmZiJ9.KqxWN4DLwxvXZ_VGazoNTpIJmWseauv_uUJ56lSZdoA"}'
Response Body

Same as Login Response Body