Basics
Now the service and the datamodel has been clarified, let's have a look on how to consume the API.
Webservice location & URL
The webservice for service provisioning and configuration is available on the internet. The FQDN at which the service is exposed might change in the future. Current location is:
https://apioaas-prov.netaxis.cloud/
The API consume the API, this FQDN has to be appended with api/v01
Authentication
To authenticate, a user account is required. If you don't have a user account, but you need one, please contact your sales representative.
Logging in
Once you have an account, you can log in by posting your user credentials against following endpoint:
POST /api/v01/auth/login
Body
| Parameter | Type | Description | Required? |
|---|---|---|---|
username | string | Username of the user that wants to consume the API | yes |
password | string | User password | yes |
Return codes
| Statuscode | Description |
|---|---|
200 | Authentication succeeded. In case your device is trusted, tokens will be provided that can be used to make subsequent API calls. Else a 2-factor authentication token will be provided (see further) |
401 | Invalid or unknown credentials |
2 Factor authentication
The platform keeps track of user agents and their IP addresses that consume the API. When you try to logon from a source that was not registered previously, tokens will not be provided immediately upon successful authenticaiton. Instead, the API will return a 200 with in the response body a string 2fa_payload.
Example:
{
"2fa_payload":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoyNTEsImF1ZCI6IjJmYS1zZXJ2ZXIiLCJleHAiOjE2MzUzNjkyNzcsImlzcyI6ImFwaW8ifQ.LMLOuf54Wsos9on1R8LdZyCOur3GarZiHoswFom-BFVdABAe-wUi_ys2peXBVk-QGkzUaNH5drxvw4qiHs00X_N-G8_OIrCseN9Gig85VUuoGd6ZEENT2VovmPe5FoU3_nttGBgJegVPd0bH4AoB8_jMkYpGRwYLuHlw1sEg8uTYqVa2tTX-PhPOnYOiylL1j050YleUNXhv9BK2MxHH1-ivr5kVKqv9Fo6RQ1Wy--TspNLUZ9ZeqXbrao1xzUfaJuA0rGb6ojjMesRopOl-2KEDKSjaWtvZBPrKuOgC4oasZQl50-M5LwCq7Psoo-U2Llhy_iEF6ql-qaG3wOSXtA"
}The user will receive subsequently a mail with a code challenge.
WARNING
In case no mail address is associated to the user, the 2-factor authentication will be enforced.
The code challenge that is sent per mail must then subsequently be posted on the following endpoint: POST /api/v01/auth/2fa
| Parameter | Type | Description | Required? |
|---|---|---|---|
2fa_payload | string | 2FA payload that was received while trying to authenticate initially | yes |
code | string | Code challenge that was provided out of band (per mail) | yes |
trust | string | If true, the location will be registered as trusted location | no |
Example:
{
"2fa_payload": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoyNTEsImF1ZCI6IjJmYS1zZXJ2ZXIiLCJleHAiOjE2MzUzNjkyNzcsImlzcyI6ImFwaW8ifQ.LMLOuf54Wsos9on1R8LdZyCOur3GarZiHoswFom-BFVdABAe-wUi_ys2peXBVk-QGkzUaNH5drxvw4qiHs00X_N-G8_OIrCseN9Gig85VUuoGd6ZEENT2VovmPe5FoU3_nttGBgJegVPd0bH4AoB8_jMkYpGRwYLuHlw1sEg8uTYqVa2tTX-PhPOnYOiylL1j050YleUNXhv9BK2MxHH1-ivr5kVKqv9Fo6RQ1Wy--TspNLUZ9ZeqXbrao1xzUfaJuA0rGb6ojjMesRopOl-2KEDKSjaWtvZBPrKuOgC4oasZQl50-M5LwCq7Psoo-U2Llhy_iEF6ql-qaG3wOSXtA",
"code": "094999",
"trust": true
}When the challenge was posted successfully, the API will return a set of tokens that can be used for subsequent API calls (see token management)
Token management
Making API calls
Once the authentication has been done successfully, a set of token will be returned:
| Parameter | Type | Description |
|---|---|---|
access_token | string | Short lived token (valid for 2 minutes) that has to be used as Bearer token for all subsequent API calls |
refresh_token | string | Long lived token (valid for 48 hours) that can be used to renew the access_tokenwithout having to re-authenticate |
Example tokens returned by the login API:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxMyw32113",
"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxMw424114"
}Refreshing the access token
As long as your access_tokenis valid, you can use this token as Bearer token. When this token is no longer valid, the API will return a 401. This is the sign to try to refresh the token using the provided refresh_token. This can be done by: GET /api/v01/auth/access_token
while using the refresh_token as Bearer token
As long as the refresh token is valid, this API will return a 200 OK and provide a new access_token. To renew the refresh token, a new login cycle is needed.
Storing tokens at client side
As you can understand, these tokens are quite sensitive data. The refresh token is even more sensitive than the access token as it remains valid for several hours/days. Once a hacker is able to steal your token, he will be able to make API calls on your behalf.
To make sure a hacker cannot steal your tokens, please store them safely while building your web application that consumes the API. If it is a browser application, make sure you encrypt the tokens before storing them on the local storage.
Invalidating tokens (logging off)
To invalidate your tokens (which is the same as logging off), use this:
GET /api/v01/auth/log_off
Use your access token as bearer token.
Authorization
User types
Obviously, the platform supports different types of users:
- system admins: have access to all resources on the platform
- distributor admins: have access to all resources of all their resellers, their direct as well as indirect customers.
- reseller admins: have access to all resources of their direct customers.
- tenant admins: only have access to their tenant, subscriptions and associated services. They are not allowed to make billable changes
The API will enforce these rules. When you try to access, create or modify a resource to which you are not authorized, you will receive a `403 Forbidden``
Fetching your user profile
To understand which user profile is associated to your user, use following endpoint:
GET /api/v01/system/users/local
Success
Body
Only the relevant parameters are documented:
| Parameter | Type | Description | Conditional? |
|---|---|---|---|
username | string | Username that the user has to use to log in to the portal | no |
email | string | Email address of the user. All communication (welcome mail, reset password, 2FA) will happen to this e-mail | no |
firstname | string | First name of the user | no |
lastname | string | Last name of the user | no |
mobilenumber | integer | Mobile number of the user | no |
language | string | ISO 639-1 notation representing the preferred language of the user | no |
timezone | string | Timezone of the user | no |
admin_of | array | Array of objects (usually 1 object) that describes the instance (level + UUID) on which behalf the user can take actions. More details on the objects itself can be found under profile | no |
profile | object | Object containing a detailed subscription of the authorizations the user has. This profile forms the foundation of the role based access system as it clearly describes what the user is allowed to do and what not. More details can be found under profile | no |
registered_on | integer | Creation time of the user profile | no |
admin_of Object
admin_of is an array
The backend returns an array of objects. In the future a user might be admin of multiple instances.
| Parameter | Type | Description | Conditional? |
|---|---|---|---|
level | string | Represents the level for which the user is administrator. Possible values are:
| no |
reference | string | Can be empty. If not empty it contains the UUID of the instance for which the user is authorized | no |
owner | object | See owner. Only present when used without query parameter or attached to a distributor or reseller | yes |
profile object
The profile object in the user profile describes with API authorizations the user in question has.
| Parameter | Type | Description | Conditional? |
|---|---|---|---|
id | string | Universal unique id uniquely identifying the tenant | no |
name | string | Name the tenant | no |
created_on | timestamp | Indicates when the profile was created | no |
updated_on | timestamp | Indicates when the profile was last updated | yes |
api_rules | array | Array of objects of which each object is an API rule. See api_rules for more details | no |
api_rule object
The profile object in the user profile describes with API authorizations the user in question has.
| Parameter | Type | Description | Conditional? |
|---|---|---|---|
id | integer | Index of the rule | no |
method | string | HTTP method for which the rule applies. Possible values are:
| no |
url | string | Regular expression that is used by the backend to validate whether the user is authorized to access a given API endpoint | no |
allowed | boolean | Indicates whether a certain route must be blocked. By default, everything is blocked except what is explicitly allowed by these rules | yes |
name | boolean | A label that is used to describe the API rule. The main purpose of this field is to indicate to the portal what kind of right the rule concerns. It is the foundation of role based access. | yes |
profile_id | integer | ?? | no |
created_on | timestamp | Indicates when the rule was created | no |
Example:
{
"admin_of": [
{
"level": "distributor",
"reference": "19cb4904-2b26-4982-8706-dfac061c07af"
}
],
"email": "bart.coelmont@gmail.com",
"entity": "",
"first_name": "Bart",
"groups": [],
"id": 30,
"is_system": false,
"language": "en",
"last_name": "Coelmont",
"local_user": true,
"mobile_number": "+32478604974",
"modules": [
"orchestration",
"bulk",
"manualActions"
],
"profile": {
"id": 5,
"name": "distributor_admin",
"home": "",
"available": true,
"created_on": "2021-10-28T07:24:12.124448Z",
"updated_on": "2021-12-03T23:03:50.783802Z",
"api_rules": [
{
"id": 10,
"method": "get",
"url": "/api/.*/{draas_instance}/distributors/.*-.*-.*-.*-.*",
"allowed": true,
"profile_id": 0,
"name": "distributors.instance.read",
"created_on": "2021-12-03T23:03:50.783802Z"
},
{
"id": 11,
"method": "put",
"url": "/api/.*/{draas_instance}/distributors/.*-.*-.*-.*-.*",
"allowed": true,
"profile_id": 0,
"name": "distributors.instance.update",
"created_on": "2021-12-03T23:03:50.783802Z"
},
{
"id": 12,
"method": "get",
"url": "/api/.*/{draas_instance}/resellers",
"allowed": true,
"profile_id": 0,
"name": "resellers.list",
"created_on": "2021-12-03T23:03:50.783802Z"
},
{
"id": 13,
"method": "get",
"url": "/api/.*/{draas_instance}/resellers/.*-.*-.*-.*-.*",
"allowed": true,
"profile_id": 0,
"name": "resellers.instance.read",
"created_on": "2021-12-03T23:03:50.783802Z"
},
{
"id": 14,
"method": "put",
"url": "/api/.*/{draas_instance}/resellers/.*-.*-.*-.*-.*",
"allowed": true,
"profile_id": 0,
"name": "resellers.instance.update",
"created_on": "2021-12-03T23:03:50.783802Z"
},
{
"id": 15,
"method": "post",
"url": "/api/.*/{draas_instance}/resellers",
"allowed": true,
"profile_id": 0,
"name": "resellers.create",
"created_on": "2021-12-03T23:03:50.783802Z"
},
{
"id": 16,
"method": "delete",
"url": "/api/.*/{draas_instance}/resellers/.*-.*-.*-.*-.*",
"allowed": true,
"profile_id": 0,
"name": "resellers.instance.delete",
"created_on": "2021-12-03T23:03:50.783802Z"
},
{
"id": 17,
"method": "get",
"url": "/api/.*/{draas_instance}/tenants",
"allowed": true,
"profile_id": 0,
"name": "tenants.list",
"created_on": "2021-12-03T23:03:50.783802Z"
},
{
"id": 18,
"method": "get",
"url": "/api/.*/{draas_instance}/tenants/.*-.*-.*-.*-.*",
"allowed": true,
"profile_id": 0,
"name": "tenants.instance.read",
"created_on": "2021-12-03T23:03:50.783802Z"
},
{
"id": 19,
"method": "put",
"url": "/api/.*/{draas_instance}/tenants/.*-.*-.*-.*-.*",
"allowed": true,
"profile_id": 0,
"name": "tenants.instance.update",
"created_on": "2021-12-03T23:03:50.783802Z"
},
{
"id": 20,
"method": "post",
"url": "/api/.*/{draas_instance}/tenants",
"allowed": true,
"profile_id": 0,
"name": "tenants.create",
"created_on": "2021-12-03T23:03:50.783802Z"
},
{
"id": 21,
"method": "delete",
"url": "/api/.*/{draas_instance}/tenants/.*-.*-.*-.*-.*",
"allowed": true,
"profile_id": 0,
"name": "tenants.delete",
"created_on": "2021-12-03T23:03:50.783802Z"
}
],
"accesses": []
},
"profile_id": 5,
"properties": {
"draas_instance": "draas_v1"
},
"registered_on": "2021-12-03T22:04:37.64803Z",
"roles": [],
"support_reset_password": true,
"timezone": "+01:00",
"token": null,
"trusted_locs": [],
"ui_data": null,
"ui_profile": "user",
"username": "bcoe_distributor_admin"
}