Use TrustBuilder.IO API with Postman

TrustBuilder.IO API endpoints are protected by OAuth2 access tokens. When calling a trustBuilder.IO API endpoint, you need to supply a valid access token in the HTTP Authorization header. You should prefix the value with the bearer, which specifies the authentication scheme used.

1. Get client credentials in TrustBuilder

In this configuration, we use the Client credentials grant.

Go to Access Management > Service Providers.
Click on + Add New SP.
Click on OAUTH Client SP.
Configure the settings:

Setting	Description	Value
GENERAL
Display name	Enter a display name for this new OAuth Client SP	TrustBuilder.io API
Authentication Scheme	Select the authentication scheme to use.	IDHUB Default Scheme, which is the default authentication scheme
Subject	Select the primary user attribute that is used to identify the user.	“IDHub UserID”, which is the fields used for username.
Manage Certificates	Add a certificate.	Context → SIGNING (KEY) Certificate → idhub-signing
OAUTH CLIENT SP SETTINGS
OAuth Policy	Select the OAuth protocol version.	OAuth 2.0
Callback URLs		https://oauth.pstmn.io/v1/callback
Scope	Check the scopes.	administrator, config:read, config:write, openid, userdata, users:read, users:write
Client Profile	Select the application type: public app (not able to hold credentials securely) or confidential app (able to hold credentials securely)	CONFIDENTIAL
Client Authentication Enabled	Enable the grant type “Client Credentials”
Client Authentication Type	Select where to include client authentication parameters. HTTP Basic Authentication Scheme: The client's authentication parameters are included in the http Authentication header HTTP POST from body: The client's authentication parameters are included in the body of the http request, which are posted to the server Client secret JWT: The client's authentication parameters are added as a JWT, that is signed using a shared secret. Private Key JWT: The client's authentication parameters are added as a JWT, that is signed using the client's private key.	HTTP POST from body
Access token type	Select the type of access token	JWT
Access Token Time To Live	Define the access tokens lifetime	Ex: 7 days

Click on Save & Close.
The client credentials (client ID and client Secret) are generated.
Write it down since it will not be shown again.

2. Generate an access token in Postman

Log in to Postman.
Set the Authorization settings of a collection (or a request):
- Type → OAuth 2.0
- Add auth data to → Request Headers
- Token → Available tokens
- Header Prefix → Bearer
Configure New Token:
- Token name → define a token name
- Grant type → Client Credentials
- Access Token URL → https://{YOUR_INSTANCE}/idhub/oidc/v1/token
  Replace {YOUR_INSTANCE} with your TrustBuilder instance
- Client ID → paste the Client ID generated in TrustBuilder
- Client Secret → paste the Client secret generated in TrustBuilder
- Scope → insert the required scopes openid administrator config:read config:write userdata users:read users:write
- Client Authentication → Select “Send client credentials in body”
Click on Get New Access Token to generate an access token. After a few seconds, an access token is generated.

3. Make TrustBuilder.IO API requests in Postman

Depending on the TrustBuilder environment, the base URL should be:

https://api.trustbuilder.io/api/ for Production environment,
https://api.preview.trustbuilder.io/api/ for Preview environment.

See TrustBuilder.IO API

Let’s take an example. We will make a GET request to https://api.trustbuilder.io/api/v1/users to retrieve the list of users in the tenant.

Select the request method GET.
Enter the request URL https://api.trustbuilder.io/api/v1/users
Click on Send.

The response should list the users and their attributes.

More information about Postman requests creation