Authentication

In order to make REST calls to the Kero API:

1. Ensure that Kero has whitelisted the IPs of the various environments on your end from which you intend to connect. This should be the first step in the integration process that is discussed with your Kero representative.

2. Make a request to the /auth route below using your Kero credentials to retrieve an authentication and a refresh token.

3. Save these tokens for future usage in all interactions with the Kero API.

4. Refresh your authentication token once per 24 hours using your refresh token and the /refresh route below. Your refresh token expires every 6 months.

POST /us/auth

Request Tokens

Use your Kero API credentials to request an authentication and a refresh token.

Request body:

Field	Type	Required	Description
name	string	✅	username from credentials
password	string	✅	password from credentials

JSON

{
    "name": "username",
    "password": "some_password123!@#"
}

Curl

curl -X 'POST' \
'https://{kero-api-host}/us/auth' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"name": "username","password": "some_password123!@#"}'

JavaScript

fetch("https://{kero-api-host}/us/auth", {
"method": "POST",
"headers": {
    "accept": "application/json",
    "Content-Type": "application/json"
},
"body": JSON.stringify({
    "name": "username",
    "password": "some_password123!@#"
})
})
.then(response => response.json())
.then(console.log)
.catch(console.error);

Go

var jsonStr = []byte(`{"name":"username","password":"some_password123!@#"}`)
req, err := http.NewRequest("POST", "https://{kero-api-host}/us/auth", bytes.NewBuffer(jsonStr))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)

Response

200 OK

Schema

Field	Type	Required	Description
auth_token	string	✅	authentication token for further interactions with the Kero API
access_expires_at	integer	✅	timestamp in Unix seconds for when auth_token expires
refresh_token	string	✅	token for refreshing auth_token using the /refresh route
refresh_expires_at	integer	✅	timestamp in Unix seconds for when refresh_token expires

JSON

{
    "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRob3JpemVkIjp0cnVlLCJjaGF0X2Jhbm5lZF90aWxsIjpudWxsLCJjdXJyZW5jeSI6IlVTRCIsImV4cCI6MTY4Nzk1MDYwOCwiaXNfYmFubmVkIjpmYWxzZSwiaXNfd2hpdGVfbGlzdGVkIjpmYWxzZSwicGFydG5lcl9uYW1lIjoiQmVuZGVyIiwic3lzdGVtX25hbWUiOiJjZ18yMTU1MSIsInR5cGUiOiJBQ0NFU1MiLCJ1c2VyX2lkIjoxNDMsInVzZXJfdG9rZW4iOiI0REMwQzNGMDc3RUU1QzFGRDZEOUM4OTQzOUM1OEYwNzVGMUMzRjE0IiwidXNlcl90b3BpYyI6Ijc2MDEwMDVkLTk2ODAtNDk0Ny05NWI4LTEwNTVkYmE0ZTM5ZiIsInVzZXJuYW1lIjoiRGltYUsifQ.cPtK6IJN3i5pII5zWJUUxZFL4WooZh2Y3pkoSVJfMUM",
    "access_expires_at": 123456789,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRob3JpemVkIjp0cnVlLCJjaGF0X2Jhbm5lZF90aWxsIjpudWxsLCJjdXJyZW5jeSI6IlVTRCIsImV4cCI6MTY5MDUzNTQyMSwiaXNfYmFubmVkIjpmYWxzZSwiaXNfd2hpdGVfbGlzdGVkIjpmYWxzZSwicGFydG5lcl9uYW1lIjoiQmVuZGVyIiwic3lzdGVtX25hbWUiOiJjZ18yMTU1MSIsInR5cGUiOiJSRUZSRVNIIiwidXNlcl9pZCI6MTQzLCJ1c2VyX3Rva2VuIjoiNERDMEMzRjA3N0VFNUMxRkQ2RDlDODk0MzlDNThGMDc1RjFDM0YxNCIsInVzZXJfdG9waWMiOiI3NjAxMDA1ZC05NjgwLTQ5NDctOTViOC0xMDU1ZGJhNGUzOWYiLCJ1c2VybmFtZSI6IkRpbWFLIn0.XSTGEdniuLXB6UP3mefV8CVLoCJUjGHWYl0WbMH-wd0",
    "refresh_expires_at": 123456789
}

Error

Schema

Field	Type	Required	Description
code	integer	❌	error integer code
status	string	✅	status of the response
msg	string	❌	some description of the error
data	object	❌	any additional data for the error response

JSON

{
    "code": 1,
    "status": "INVALID SOURCE HOST",
    "msg": "any message here",
    "data": "additional data for error response"
}

POST /us/refresh

Refresh Tokens

Use your current refresh_token to request a new auth_token.

String Parameters:

Field	Type	Required	Description
token	header	✅	authentication token provided from /auth route

JSON

{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRob3JpemVkIjp0cnVlLCJjaGF0X2Jhbm5lZF90aWxsIjpudWxsLCJjdXJyZW5jeSI6IlVTRCIsImV4cCI6MTY5MDUzNTQyMSwiaXNfYmFubmVkIjpmYWxzZSwiaXNfd2hpdGVfbGlzdGVkIjpmYWxzZSwicGFydG5lcl9uYW1lIjoiQmVuZGVyIiwic3lzdGVtX25hbWUiOiJjZ18yMTU1MSIsInR5cGUiOiJSRUZSRVNIIiwidXNlcl9pZCI6MTQzLCJ1c2VyX3Rva2VuIjoiNERDMEMzRjA3N0VFNUMxRkQ2RDlDODk0MzlDNThGMDc1RjFDM0YxNCIsInVzZXJfdG9waWMiOiI3NjAxMDA1ZC05NjgwLTQ5NDctOTViOC0xMDU1ZGJhNGUzOWYiLCJ1c2VybmFtZSI6IkRpbWFLIn0.XSTGEdniuLXB6UP3mefV8CVLoCJUjGHWYl0WbMH-wd0"
}

Curl

curl -X 'POST' \
'https://{kero-api-host}/us/refresh' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'token: {auth_token} \
-d '{"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRob3JpemVkIjp0cnVlLCJjaGF0X2Jhbm5lZF90aWxsIjpudWxsLCJjdXJyZW5jeSI6IlVTRCIsImV4cCI6MTY5MDUzNTQyMSwiaXNfYmFubmVkIjpmYWxzZSwiaXNfd2hpdGVfbGlzdGVkIjpmYWxzZSwicGFydG5lcl9uYW1lIjoiQmVuZGVyIiwic3lzdGVtX25hbWUiOiJjZ18yMTU1MSIsInR5cGUiOiJSRUZSRVNIIiwidXNlcl9pZCI6MTQzLCJ1c2VyX3Rva2VuIjoiNERDMEMzRjA3N0VFNUMxRkQ2RDlDODk0MzlDNThGMDc1RjFDM0YxNCIsInVzZXJfdG9waWMiOiI3NjAxMDA1ZC05NjgwLTQ5NDctOTViOC0xMDU1ZGJhNGUzOWYiLCJ1c2VybmFtZSI6IkRpbWFLIn0.XSTGEdniuLXB6UP3mefV8CVLoCJUjGHWYl0WbMH-wd0"}'

Response

200 OK

Schema

Field	Type	Required	Description
auth_token	string	✅	authentication token for further interactions with the Kero API
access_expires_at	integer	✅	timestamp in Unix seconds for when auth_token expires
refresh_token	string	✅	token for refreshing auth_token using the /refresh route
refresh_expires_at	integer	✅	timestamp in Unix seconds for when refresh_token expires

JSON

{
    "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRob3JpemVkIjp0cnVlLCJjaGF0X2Jhbm5lZF90aWxsIjpudWxsLCJjdXJyZW5jeSI6IlVTRCIsImV4cCI6MTY4Nzk1MDYwOCwiaXNfYmFubmVkIjpmYWxzZSwiaXNfd2hpdGVfbGlzdGVkIjpmYWxzZSwicGFydG5lcl9uYW1lIjoiQmVuZGVyIiwic3lzdGVtX25hbWUiOiJjZ18yMTU1MSIsInR5cGUiOiJBQ0NFU1MiLCJ1c2VyX2lkIjoxNDMsInVzZXJfdG9rZW4iOiI0REMwQzNGMDc3RUU1QzFGRDZEOUM4OTQzOUM1OEYwNzVGMUMzRjE0IiwidXNlcl90b3BpYyI6Ijc2MDEwMDVkLTk2ODAtNDk0Ny05NWI4LTEwNTVkYmE0ZTM5ZiIsInVzZXJuYW1lIjoiRGltYUsifQ.cPtK6IJN3i5pII5zWJUUxZFL4WooZh2Y3pkoSVJfMUM",
    "access_expires_at": 123456789,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRob3JpemVkIjp0cnVlLCJjaGF0X2Jhbm5lZF90aWxsIjpudWxsLCJjdXJyZW5jeSI6IlVTRCIsImV4cCI6MTY5MDUzNTQyMSwiaXNfYmFubmVkIjpmYWxzZSwiaXNfd2hpdGVfbGlzdGVkIjpmYWxzZSwicGFydG5lcl9uYW1lIjoiQmVuZGVyIiwic3lzdGVtX25hbWUiOiJjZ18yMTU1MSIsInR5cGUiOiJSRUZSRVNIIiwidXNlcl9pZCI6MTQzLCJ1c2VyX3Rva2VuIjoiNERDMEMzRjA3N0VFNUMxRkQ2RDlDODk0MzlDNThGMDc1RjFDM0YxNCIsInVzZXJfdG9waWMiOiI3NjAxMDA1ZC05NjgwLTQ5NDctOTViOC0xMDU1ZGJhNGUzOWYiLCJ1c2VybmFtZSI6IkRpbWFLIn0.XSTGEdniuLXB6UP3mefV8CVLoCJUjGHWYl0WbMH-wd0",
    "refresh_expires_at": 123456789
}

Error

Schema

Field	Type	Required	Description
code	integer	❌	error integer code
status	string	✅	status of the response
msg	string	❌	some description of the error
data	object	❌	any additional data for the error response

JSON

{
    "code": 1,
    "status": "INVALID SOURCE HOST",
    "msg": "any message here",
    "data": "additional data for error response"
}