User management with REST API - Preview
The User Management REST API are currently in Preview Status. You may report questions or feedback to your TrustBuilder presales contact.
This documentation describes the list of Web Services that are part of TrustBuilder MFA user management API and how to call them with REST methods.
API token
The API token is a cryptic string, in this case generated by TrustBuilder, for a specific customer. Bearer authentication (also known as token authentication) uses tokens to identify and authenticate the user making the API call. This method grant access to the bearer of this token. The client must send this token in the Authorization header when sending a request to the TrustBuilder MFA REST API endpoints.
Using this application, you can generate tokens for our REST API. These API tokens have a standard duration of 13 months.
Security prerequisite
API tokens must be transported through a secure channel such as Transport Layer Security (HTTPS).
Authentication is not sufficient in exchanges when the Token is received, because the tokens could be intercepted by an malicious party if the token is not secured during transmission and storage.
Generate a new API token
To generate an TrustBuilder MFA API token, you have to use the administration Console V2.
Please, refer to the admin console V2 documentation to get more information.
Prerequisite → You should have an access to an activated console as an administrator
To generate new API token from the admin console V2:
Go to the “API token” tab
Click on “Add API token”
Indicate:
your PIN code
the expire date (or check the “Never expires”)
a description
Click on Generate.
Click on OK to validate the API Token generation.
Your API Token has successfully been generated. Click on Edit to see it and copy it.
Use the API token
To use the API Token in API calls, add the API token in the header of the REST API call .
e.g, for curl add -H "Authorization: Bearer xxxxxxyyyyyyzzzzzz" or --header 'Authorization: Bearer xxxxxxyyyyyyzzzzzz'
Test TrustBuilder MFA REST API
You can find our REST API documentation at the following address: https://kiwi.myinwebo.com/auth/apidocs/public/resources.html
You can also try our REST API at the following address (using Swagger): https://kiwi.myinwebo.com/auth/apidocs/public/ui/index.html
To be noted → In the Swagger catalog, when testing the API, please indicate a correct bearer token preceded by "Bearer " in the Authorization field.
Samples of User Management API calls
You'll find here 2 samples of API calls and their use that you'll find in our API catalog
List or search Accounts
Create an Account
Paging and "hasMore" value
Some of the results of the API calls are paginated. To know when the results exceed the value of the "limit" defined in your REST request, you must check the value "hasMore" in the result .json.
If in the result .json the value "hasMore" returns "false" it means that there is no next page and it is not necessary to continue.
If in the result .json the value "hasMore" returns "true", this means that the result of this request continues on the next page, you will have to re-launch the same request but increasing the value "page" by 1.
Initial "page" value: 0
max "limit" value: 100
List or search Accounts
GET /auth/v1/customer/services/accounts |
---|
Use GET requests to retrieve the list of user Accounts or *requested accounts of a TrustBuilder Service.
Parameters | Parameter Type | Data Type | Required ? | description |
---|---|---|---|---|
page | query | int | Optional | The requested page. Zero based. Default is 0. |
limit | query | int | Optional | The number of maximum results. Default is 50. |
Method
Request | Employed method |
---|---|
API Endpoint | https://kiwi.myinwebo.com/auth/v1/customer/services/accounts |
Verb | GET |
Content-Type: | */* |
Header | Accept: application/json |
Authentication | Authorization: Bearer xxxxxxyyyyyyzzzzzz |
CURL command to retrieve the list of accounts
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer xxxxxxyyyyyyzzzzzz' 'https://kiwi.myinwebo.com/auth/v1/customer/services/accounts?page=0&limit=50'
Invoke-RestMethod command to retrieve the list of accounts in PowerShell
$Url = "https://kiwi.myinwebo.com/auth/v1/customer/services/accounts?page=0&limit=50"
$token = "xxxxxxyyyyyyzzzzzz"
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "Bearer $token")
$ResultURL = Invoke-RestMethod -Method 'Get' -Uri $Url -Headers $headers
HTTP (JSON) Response - 200 OK
HTTP/1.1 200 OK
Content-Type: application/json
{
"page" : 0,
"size" : 1,
"limit" : 50,
"hasMore" : false,
"content" : [ {
"login" : "TrustBuilderLogin",
"email" : "email@example.com",
"language" : "fr",
"active" : true,
"role" : {
"id" : "0",
"name" : "User"
},
"createdDate" : "2019-03-30T10:48:32.936Z",
"modifiedDate" : "2019-03-30T10:48:32.936Z",
"lastAuthenticatedDate" : "2019-03-30T10:48:32.936Z"
} ]
}
Create an Account
POST /auth/v1/customer/services/accounts |
---|
Post a JSON/Data to the API endpoint to create an Account
Method
Request | Employed method |
---|---|
API Endpoint | https://kiwi.myinwebo.com/auth/v1/customer/services/accounts |
Verb | POST |
Content-Type: |
|
Header | Accept: application/json |
Authentication | Authorization: Bearer xxx.yyy.zzz |
CURL command to POST JSON data
curl -X POST --header 'Accept: application/json' --header 'Authorization: Bearer xxxxxxyyyyyyzzzzzz' 'https://kiwi.myinwebo.com/auth/v1/customer/services/accounts' -d {\"login... }
JSON data model to POST for Account creation
{
"login" : "TrustBuilderLogin",
"email" : "email@example.com",
"language" : "fr",
"active" : true,
"role" : {
"id" : "0"
},
"memberships" : [ {
"group" : {
"id" : "1"
},
"role" : {
"id" : "0"
}
} ]
}
HTTP(JSON) Response - 201 Created
HTTP/1.1 201 Created
Content-Type: application/json
{
"login" : "TrustBuilderLogin",
"email" : "email@example.com",
"language" : "fr",
"active" : true,
"role" : {
"id" : "0",
"name" : "User"
},
"memberships" : [ {
"group" : {
"id" : "1",
"name" : "group1"
},
"role" : {
"id" : "0",
"name" : "User"
}
} ],
"createdDate" : "2021-12-17T10:48:32.936Z"
"provisioningId" : 0
}
The "provisioningId"
value is the user creation source. Possible values:
0: created by the administration console
1: created by IWDS (default value)
>1: other provisioning source