¶ Using Adaptive Auth Validation
Important: This documentation is for development and testing purposes. Production endpoints like server and client validation are different and will be distributed using other channel.
In order to implement and test APIDynamcis Adaptive Auth an organization needs:
- An account in APIDynamics. Follow the steps already mentioned before.
- An API Provider
- An Adaptive Configuration
- An API Client
For steps and configuration documentation please visit APIDynamics page
¶ Performing API Calls
This is a high level use case about how API Calls are perfomed and API Clients are validated by Adaptive Auth Server.
¶ Step 1
An API Client performs a regular/common API call to the server. e.g. GET https://my.apiserver.com/listUsers
¶ Step 2
Server collects client data required to call Adaptive Auth Server for validation. This data must include
- API Provider public key
- Can be obtained in the API Provider details page
- API Client public key
- Can be obtained in the API Client details page
- API Client request headers
- Request endpoint (optional)
- e.g.
/listUsers
- e.g.
- Request method (optional)
- e.g.
GET
- e.g.
¶ Step 3
Server performs an API call to Adaptive Auth Server to validate client. See examples of how to perform the call.
¶ Code examples
curl --location 'https://developer.apidynamics.sevenhills.ai/api/dynamics/adaptive/server/validate' \
--header 'x-api-dynamics-provider-id: poHoYMiYc7UeypNlIA2hqYbozwBpDND-ctiX0ssWN7BoCqKTynZJJBCYMeo87yEW' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"client_id": "UWhNbjd4cnFzYVU0XzdwQWdsQ3QzUnZDa2l3eW4yaUVOWk9XS2V4aFgzVDNlWFVESnByR2lBZFZ6eEx0RW4ySm12RHRxVGJYSlRQdFNORmhMbE1NTGc=",
"client_request_endpoint": "/listUsers",
"client_request_headers": "{\"Accept\": \"applicaton/json\", \"Remote_Addr\": \"109.120.145.0\", \"User-Agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36\"}",
"client_request_method": "GET"
}'
const axios = require('axios');
let data = JSON.stringify({
"client_id": "UWhNbjd4cnFzYVU0XzdwQWdsQ3QzUnZDa2l3eW4yaUVOWk9XS2V4aFgzVDNlWFVESnByR2lBZFZ6eEx0RW4ySm12RHRxVGJYSlRQdFNORmhMbE1NTGc=",
"client_request_endpoint": "/listUsers",
"client_request_headers": "{\"Accept\": \"applicaton/json\", \"Remote_Addr\": \"109.120.145.0\", \"User-Agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36\"}",
"client_request_method": "GET"
});
let config = {
method: 'post',
maxBodyLength: Infinity,
url: 'https://developer.apidynamics.sevenhills.ai/api/dynamics/adaptive/server/validate',
headers: {
'x-api-dynamics-provider-id': 'poHoYMiYc7UeypNlIA2hqYbozwBpDND-ctiX0ssWN7BoCqKTynZJJBCYMeo87yEW',
'Content-Type': 'application/json',
'Accept': 'application/json',
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
import json
url = "https://developer.apidynamics.sevenhills.ai/api/dynamics/adaptive/server/validate"
payload = json.dumps({
"client_id": "UWhNbjd4cnFzYVU0XzdwQWdsQ3QzUnZDa2l3eW4yaUVOWk9XS2V4aFgzVDNlWFVESnByR2lBZFZ6eEx0RW4ySm12RHRxVGJYSlRQdFNORmhMbE1NTGc=",
"client_request_endpoint": "/listUsers",
"client_request_headers": "{\"Accept\": \"applicaton/json\", \"Remote_Addr\": \"109.120.145.0\", \"User-Agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36\"}",
"client_request_method": "GET"
})
headers = {
'x-api-dynamics-provider-id': 'poHoYMiYc7UeypNlIA2hqYbozwBpDND-ctiX0ssWN7BoCqKTynZJJBCYMeo87yEW',
'Content-Type': 'application/json',
'Accept': 'application/json',
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
¶
¶ Step 4
API Server to analize response from Adaptive Auth Server and HTTP Status Code
API Client is allowed. So, API Server can continue performing API call requested by API Client.
{
"transaction_id": "abfe6960-7f87-4ed2-80bc-143e024aee95",
"validation_result": {
"score": 100,
"decision": "ALLOW",
}
}
When Adaptive Auth Server response is HTTP 204 - No Content, is because the client being validated is not associated linked to an adaptive auth API and/or configuration. In this case, API Server must stop performing API call and reject it.
{
"error":"Request does not correspond to an adaptive authentication method",
"detail":"API authentication method must be ADAPTIVE"
}
API Client must resolve a TOTP challenge. This is a special case when this status code and Adaptive Auth Server response is received, another flow must be followed in order to resolve it and securely identify API Client. See here for specific details tbd.
{
"transaction_id": "abfe6960-7f87-4ed2-80bc-143e024aee95",
"validation_result": {
"score": 75,
"decision": "CHALLENGE",
}
}
When the API Client validation is forbidden two things might have happened.
- Any entity is not active in the system, so API call must be rejected.
- API Client
- API Provider
- Provider API (the one accessed by the API Client)
- The API Client is denied, API call must be rejected.
When API Client is denied, Adaptive Auth Server response is like:
{
"transaction_id": "abfe6960-7f87-4ed2-80bc-143e024aee95",
"validation_result": {
"score": 50,
"decision": "DENY",
}
}
Otherwise, Adaptive Auth Server response is like:
{
"error": "string",
"detail": "string"
}
When the API Client validation is Not Found then, any entity does not exist in the system, so, API call must be rejected.
- API Client
- API Provider
- Provider API (the one accessed by the API Client)
{
"error": "string",
"detail": "string"
}
¶
¶ How to resolve 401 - Unauthorized
When an API Client is challenged, this flow must be used.
¶ Step 1 - Request TOTP token
Note that ONLY API Server will be able to request TOTP tokens from Adaptive Authentication Server. So when an API Client is challenged and API Client request an TOTP token from server, this token must be requested to the API Server and the API Server will request it to Adaptive Authentication Server.
These code examples here are going to be used by an API Server who requests TOTP tokens for an API Client.
curl --location 'https://developer.apidynamics.sevenhills.ai/api/dynamics/totp/client/generate?tid=7c85fff6-adc5-4f72-8de2-a4c81b765af9' \
--header 'x-api-dynamics-provider-id: poHoYMiYc7UeypNlIA2hqYbozwBpDND-ctiX0ssWN7BoCqKTynZJJBCYMeo87yEW' \
--header 'x-api-dynamics-client-id: UWhNbjd4cnFzYVU0XzdwQWdsQ3QzUnZDa2l3eW4yaUVOWk9XS2V4aFgzVDNlWFVESnByR2lBZFZ6eEx0RW4ySm12RHRxVGJYSlRQdFNORmhMbE1NTGc=' \
--header 'Accept: application/json' \
const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: 'https://developer.apidynamics.sevenhills.ai/api/dynamics/totp/client/generate?tid=7c85fff6-adc5-4f72-8de2-a4c81b765af9',
headers: {
'x-api-dynamics-provider-id: poHoYMiYc7UeypNlIA2hqYbozwBpDND-ctiX0ssWN7BoCqKTynZJJBCYMeo87yEW',
'x-api-dynamics-client-id': 'UWhNbjd4cnFzYVU0XzdwQWdsQ3QzUnZDa2l3eW4yaUVOWk9XS2V4aFgzVDNlWFVESnByR2lBZFZ6eEx0RW4ySm12RHRxVGJYSlRQdFNORmhMbE1NTGc=',
'Accept': 'application/json'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
url = "https://developer.apidynamics.sevenhills.ai/api/dynamics/totp/client/generate?tid=7c85fff6-adc5-4f72-8de2-a4c81b765af9"
payload = {}
headers = {
'x-api-dynamics-provider-id: poHoYMiYc7UeypNlIA2hqYbozwBpDND-ctiX0ssWN7BoCqKTynZJJBCYMeo87yEW',
'x-api-dynamics-client-id': 'UWhNbjd4cnFzYVU0XzdwQWdsQ3QzUnZDa2l3eW4yaUVOWk9XS2V4aFgzVDNlWFVESnByR2lBZFZ6eEx0RW4ySm12RHRxVGJYSlRQdFNORmhMbE1NTGc=',
'Accept': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
¶
¶ Analyze TOTP Token response
API Client to analyze response from Adaptive Auth Server and HTTP Status Code
API Client provided a valid TOTP token and it is allowed. So, API Server can continue performing API call requested by API Client.
{
"totp": "919103",
"token_result": {
"token": "919103",
"now": "2025-01-29T22:58:09.105791+00:00",
"totp_for_time": "2025-01-29T23:58:09.105791+00:00",
"expirity_time": 1,
"expirity_time_unit": "HOUR"
}
}
When Adaptive Auth Server response is HTTP 204 - No Content, is because the client requesting a TOTP token is not associated linked to an adaptive auth API and/or configuration, so, client won't be able to generate a token.
{
"error":"Request does not correspond to an adaptive authentication method",
"detail":"API authentication method must be ADAPTIVE"
}
When the API Client validation is forbidden two things might have happened.
- Any entity is not active in the system, so API call must be rejected.
- API Client
- API Provider
- Provider API (the one accessed by the API Client)
{
"error": "string",
"detail": "string"
}
When the API Client validation is Not Found then, any entity does not exist in the system, so, API call must be rejected.
- API Client
- API Provider
- Provider API (the one accessed by the API Client)
{
"error": "string",
"detail": "string"
}
¶
¶ Step 2 - API Client send TOTP token to API Server for validation
This HTTP Request must be defined and implemented between API Clients and API Server using their own contract and API definition since it is internal between them.
Something to take into account are the required parameters that Adaptive Auth Server is expecting to validate an API Client.
¶ Required parameters to be sent
| Parameter name | Description | Example |
|---|---|---|
| tid | Transaction Id | 7c85fff6-adc5-4f72-8de2-a4c81b765af9 |
| totp | TOTP token | 919103 |
¶ Step 3 - API Server to validate provided TOTP token
curl --location 'https://developer.apidynamics.sevenhills.ai/api/dynamics/totp/server/validate?tid=7c85fff6-adc5-4f72-8de2-a4c81b765af9&totp=919103' \
--header 'x-api-dynamics-provider-id: poHoYMiYc7UeypNlIA2hqYbozwBpDND-ctiX0ssWN7BoCqKTynZJJBCYMeo87yEW' \
--header 'Accept: application/json'
const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: 'https://developer.apidynamics.sevenhills.ai/api/dynamics/totp/server/validate?tid=7c85fff6-adc5-4f72-8de2-a4c81b765af9&totp=919103',
headers: {
'x-api-dynamics-provider-id': 'poHoYMiYc7UeypNlIA2hqYbozwBpDND-ctiX0ssWN7BoCqKTynZJJBCYMeo87yEW',
'Accept': 'application/json'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
url = "https://developer.apidynamics.sevenhills.ai/api/dynamics/totp/server/validate?tid=7c85fff6-adc5-4f72-8de2-a4c81b765af9&totp=919103"
payload = {}
headers = {
'x-api-dynamics-provider-id': 'poHoYMiYc7UeypNlIA2hqYbozwBpDND-ctiX0ssWN7BoCqKTynZJJBCYMeo87yEW',
'Accept': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
¶
¶ Step 4
API Server to analyze response from Adaptive Auth Server and HTTP Status Code
API Client provided a valid TOTP token and it is allowed. So, API Server can continue performing API call requested by API Client.
{
"totp_valid": true
}
When the API Client validation is forbidden two things might have happened.
- Any entity is not active in the system, so API call must be rejected.
- API Client
- API Provider
- Provider API (the one accessed by the API Client)
- TOTP Token does not match transaction token
{
"error": "string",
"detail": "string"
}
When the API Client validation is Not Found then, any entity does not exist in the system, so, API call must be rejected.
- API Client
- API Provider
- Provider API (the one accessed by the API Client)
- Transaction
- TOTP Token
{
"error": "string",
"detail": "string"
}