API Reference
API Access Authentication
An access token is a bearer token issued by an authorization server to a client application. It represents the authorization granted to the client to access specific resources or perform actions on behalf of the resource owner.
Key Characteristics:
- Short-lived: Access tokens typically have a limited lifespan to enhance security.
- Bearer Token: This means the client presents the access token in the authorization header of requests to protected resources.
- Scope-based: Access tokens often incorporate scopes, defining the specific permissions granted to the client.
- Secret: Access tokens should be treated as secret and never exposed to the end-user.
Purpose:
- Authorization: Validates the client’s identity and permissions for accessing protected resources.
- Delegation: This enables the client to act on behalf of the resource owner.
- Security: Protects resources from unauthorized access.
Additional Notes:
- Access tokens are often used in conjunction with refresh tokens to obtain new access tokens when they expire.
Get Access Token
Get an Access Token by utilising an authorised Secret Key. The API will return the Access Token along with its expiry and Refresh Token.
To obtain a renewed access token after the expiry, initiate the same API call using a valid Refresh Token.
- URL: <base url>/auth/v1/accessToken
- Request Method: POST
Payload
Key | Type | Pass in | Description |
---|---|---|---|
secretKey * | String | Body | Refresh Token provided in the previous call of “accessToken” made with grant type secret Mandatory if grantType is refresh |
refreshToken | String | Body | Refresh Token provided in the previous call of “accessToken” made with grant type secret Mandatory if grantType is refresh |
grantType * | String | Body | This identifies that accessToken will be granted via which medium Possible mediums are: secret | refresh |
Response
Key | Type | Description |
---|---|---|
header | JSON | JSON object that describes the return code and message. |
body | JSON | JSON object that returns access token, refresh token, expiry (in seconds), and reseller ID. |
accessToken | String | This will be used in the header (X-AccessToken) for authentication of API’s. |
refreshToken | String | This will be used in the next accessToken call with the refreshToken and grantType set to refresh. |
expiry | int | This is the number of seconds for which the accessToken is valid. |
resellerId | int | This is the partner account ID. |
resellerUid | String | This is the unique identifier of the partner account. |
POST /auth/v1/accessToken
curl 'https://atomapi.com/auth/v1/accessToken' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
-d 'secretKey=SECRET_KEY_GOES_HERE&grantType=secret'
Sample Response
{
"header": {
"code": 1,
"message": "success"
"response_code": 1
},
"body": {
"accessToken": "xxxxxxxx",
"refreshToken": "xxxxxxxx",
"expiry": xxxxxxxx,
"resellerId": "xxxxxxxx"
"resellerUid": "xxxxxxxx"
}
}