To access Swagger UI-enabled endpoints and test your API quickly without having to format the request in Postman or other REST client tools, you must have administrator access to your Genetec ClearID™ sandbox account.
More information on Accounts for dev/test sandbox
1 - Authenticate the Swagger UI of the API endpoints
For each API Endpoint the table contains the Swagger UI url, which is the documentation of the endpoint.
For this example, we will use the Identity Service in the dev sandbox environment.
https://identityservice-demo.clearid.io/swagger/
Once you open that page, you must click Authenticate at the top.
In the Available authorizations Window, check openid. Do not put anything in client_id.
You can now click Authorize.
If the browser is already connected to ClearID, it will redirect you to the login page. Enter the email and password you received for your ClearID account.
Once this process is completed, the ClearID STS creates an access token (bearer) available for subsequent API calls.
2 - Try your first API call
For this example, we will use a simple call of the Identity Service that lists Identities that do not have an external ID.
Identity Service Swagger UI
https://identityservice-demo.clearid.io/swagger
In the swagger UI, locate and expand the call:
GET /api/v2/accounts/{accountId}/identities List identities by external id
Click Try it out
accountid
This mandatory parameter is required in almost all API calls.
You have administrator privileges in your ClearID account. You can check your privileges by looking at the URL of the ClearID portal after you authenticate:
In https://demo.clearid.io/fy6uk0m5jx, the accountid is fy6uk0m5jx
When building a generic integration, you should get the accountid from a JSON configuration file that can be downloaded from the ClearID Portal. See Authentication for more information on the JSON file.
externalid
Put 123 as value for this example.
The externalid should be a unique identifier coming from your employee management system. It should be something immutable that can be used as a unique key to link an Identity between ClearID and the source of truth (HR, Payroll, DB...).
continuation
Leave this parameter empty for this example.
This token is required if you have many identities that correspond to the same external id. The system will return the first batch of identities and provide a continuation token in the response, which will return the next batch of identities.
In summary, for the first call, you should never provide any value to get the first batch.
Click Execute.
At this point, the API should return 200 Success with an empty array because no identity has the external ID "123".
{
"identities": []
}3 - Modify your own Identity in the web portal
Open the ClearID dev sandbox environment. The URL you received by email should be: https://demo.clearid.io
1 - Click My Profile in the top menu.
2 - Click Manage in the left menu.
NB: If you do not have the Manage option, it is because your account is not an administrator.
It should show a page that looks like the one below.
Enter 123 in the External ID field.
4 - Try again with external ID
In the Identity Service swagger UI, locate and expand the call:
GET /api/v2/accounts/{accountId}/identities List identities by external id
Now, try again with your accountid and 123 as externalid.
This time the API should return your identity in the array similar to the one below.
{
"identities": [
{
"identityId": "480ea883-cf19-426a-8cd2-1c9fdc3c12ef",
"eTag": "db69d035bb9e0a5d24d2ae55907e1d8a2f1322f6",
"status": "Active",
"firstName": "John",
"lastName": "Smith",
"displayName": "John Smith",
"countryCode": "USA",
"email": "jsmith@mycompany.com",
"privateData": {
"employeeNumber": ""
},
"companyData": {},
"systemData": {
"partitions": [
"/cleariddemos/"
],
"externalId": "123",
"provisioningAttributes": [
{
"name": "LEVEL3"
}
]
},
"createdBy": "abc23123@GENETEC.COM",
"creationDateUtc": "2018-10-30T16:40:30.869477Z",
"lastModifiedBy": "abc23123@genetec.com",
"lastModificationDateUtc": "2021-12-21T16:02:33.0173585Z",
"ordinal": 5,
"isDeleted": false
}
]
}