Entrust Identity as a Service Administration API
This document describes how to manage your Identity as a Service account using Administration (Admin) API calls. This API allows you to seamlessly perform administrative actions on Identity as a Service without logging in to the Identity as a Service Administrator portal.
Prerequisites
Confirm the following before executing the Admin API calls included in this guide:
- An Admin API application has been created on your Identity as a Service account. The application must be configured with a role that has the permissions needed by your application. Identity as a Service allows you to download a JSON file once the application is created.
- The Application ID and Shared Secret parameter values are easily accessible. They must be entered into the body of the Admin APi request. The required values are displayed after creating the Administration API application on Identity as a Service. Upon creation, you can either copy these values to your clipboard or download them as a JSON file.
- The Admin API application configuration data has been downloaded and is available for use.
Identity as a Service Administration APIs
Identity as a Service administration APIs are grouped into the following categories. You can only perform the API calls permitted by the role assigned to your Administration API application on Identity as a Service. See the Identity as a Service Administrator Help for more information on Identity as a Service roles:
Admin Authentication
These APIs facilitate authentication between your Admin API application and Identity as a Service. You must make this call before making any other Admin API calls. The call generates an authentication token value that must be included in all other Admin API requests.
The Admin API authentication response includes the token's expiration time. For instance:
{
"authToken": "GLrKMuDGiIWPJooDRFTZIHc65RyjJBiPdy4b5xNR8fKxXfwy4tbSIvh+xiFHlJ2p6tm3FuOZ34sxjCHYbDa77eLrxFcMuwYjRMmLWsUIGfkpfg33Wb/5X01Xag4Vdjz5DpVKfCg/OL2rnd4tfCfzM9FoY+vY/sllGgRtQkGeZodsi+QvazqQS1iJ5e6i5ouR05P52YsLgmMlZ4mUfH3JiXZmkkAJvXuM3oj9msi/a4ULWeUGYW5oHM5Gs6ab37baa5xzVykzowHdIoZMVeC8+zVqDr+yXTAHVysBYQHngyckgBizDc2g49RgRTEz2k+yRIvwUU5swGzKtgt6kYtyyFM8YdeODB59Fkl8w5mQQDpxIyZcclCFv2C+MBWdnbM0kJIgNtE1ZeRA+zxwS6avE8EKw3T9Nczs6KBfycV3NxgxTvTQIxNi3kPA8XdJtAmCkUR/gyLkqJXk7bGDvFo4+rWR4uX2XxHm2NZGTNA1QezK96Y7JVjImfoHlUJnxGm207/kVPIVtSUD+6XuEl0uVvrtnTPmQnpq3P0gTYvon3Cw1caQvIydtrUv4yfs4Q/WVvSF3GQh3uet/IkUeGbkxLn43CSVz2hCQoeF8jxIoiJuSAxs1e3phylp0plijvok01Tbit6um/x4tK5UZYCRZYmeSD/ltXGtZNOoA4YHh5cDK+KcDy2tuWaexi2Hf+nJ5adqiMHwuozIH69Eqc6OZ9o86t75mIdux8zLgWt0T3SFOphtCvF0L8BdxICrEXGMDhguRRH7f+/IPU0ggFwnxsIV2a3c4oOayFfHwVSg4rGSKfWuWtkfNavA8RI5y6JOKzMrulrdg+gzuBMms2nKn38HNIRu2pKMVzQ2jU8CrtPgOT8=",
"expirationTime": "2020-01-23T16:30:58Z",
"creationTime": "2020-01-23T16:15:58Z"
}
If you use this authentication token to make requests after it expires, the service will return an UNAUTHORIZED response code (401) and you will need to reauthenticate to obtain a new token.
Some workarounds to prevent this are:
- Always reauthenticate before making a request; or
- Track the expiration time and reauthenticate when you detect that it has expired; or
- Send an OPTIONS request to the same end-point to detect whether the token has expired. This can be useful with end-points receiving a large payload such as images where the token can expire before the request has completed. In these cases the request may fail with a 500 error.
When an admin API application authenticates, there is an option to enable a web session to add additional security to the session. This is done by setting the enableWebSession argument passed to the authentication controller to true. When a web session is enabled, an HTTP session cookie named Identity as a Service_SESSION_ID will be returned with the authentication results. This cookie must be included with all subsequent admin API calls along with the authentication token.
Users
These APIs facilitate user management operations on an Identity as a Service account.
Smart Credentials
The Entrust® Mobile Smart Credential (MSC) application allows users to perform authentications to their Identity as a Service account and configured applications. This API call facilitates mobile smart credential management operations on an Identity as a Service account.
Tokens
These APIs facilitate hardware and soft token management operations on an Identity as a Service account.
FIDO2/Passkey Tokens
These APIs facilitate management of FIDO2 tokens. FIDO2 tokens can be registered, viewed, deleted and updated.
Grid Cards
Grid authentication uses cards with a grid as the authentication lookup tool. This API call facilitates Grid Card management operations on an Identity as a Service account.
Temporary Access Codes
Temporary Access Codes can be used to log in when a user cannot access their one-time passcode (OTP), Grid Card, or token authenticator. This API call facilitates Temporary Access Code management operations on an Identity as a Service account.
KBA - Knowledge-based Authenticators
Knowledge-based authentication (or knowledge-based authenticators) (KBA) (also known as question-and-answer (Q&A) authentication) allows users to authenticate to SAML application accounts using Identity as a Service by providing the correct answer to one or more preregistered questions. This API call facilitates Knowledge-based Authenticator management operations on an Identity as a Service account.
Passwords
There are two types of password authenticators available on Identity as a Service —Identity as a Service passwords and Active Directory (AD) passwords. Identity as a Service passwords are passwords that can be manually or automatically assigned to users on Identity as a Service. Active Directory (AD) passwords are passwords that have already been assigned to a user on their corporate directory - not through Identity as a Service. This API call facilitates password management operations on an Identity as a Service account for either type of password.
OTPs
These APIs facilitate OTP management operations on an Identity as a Service account.
User Risk-based authentication (RBA) Settings
Risk-based authentication (RBA) identifies the level of risk associated with a user who tries to authenticate. This API call facilitates Risk-based authentication management operations on an Identity as a Service account.
Machine authenticators
Machine Authentication (MA) provides identification information on the Web browser being used to access a SAML application. This API call facilitates Machine Authenticator management operations on an Identity as a Service account.
Face Biometric
Face Biometric authentication uses an Onfido account to allow users to authenticate with biometric security. Face Biometric can be viewed, deleted, updated and created for a user if they already exist in Onfido.
User Attributes
User attributes are the information fields listed as part of each user's Profile information. This API call facilitates user attribute management operations on an Identity as a Service account.
Roles
Roles control what operations a user can perform on their Identity as a Service account. These roles distinguish the amount of access given to each account, ranging from administrators with full access to end users (who can only access the user portal features).This API call facilitates role management operations on an Identity as a Service account.
Groups
An Identity as a Service group is a collection of users given access to applications based on the resource rules they are assigned to. This API call facilitates group management operations on an Identity as a Service account.
Reports
These APIs allow you to access the Audit Log on your Identity as a Service account. This Log lists the actions performed on your account within a period of time.
Settings
These APIs provide management of the settings used to configure Identity as a Service behavior. Settings that can be managed using the administration API include General settings, OTP settings, Token settings, Password Reset settings and Onfido Account settings.
Applications
These APIs provide management of authentication API applications using the administration API.
Resource Rules
Resource rules define what authenticators are allowed to authenticate to an application. The resource rules APIs provide management of resource rules and authentication flows using the administration API. An authentication flow will define a list of possible authentication paths that a user can take when accessing an application. For instance, the User Login flow allows access to an application after providing a user identifier (User ID) and a combination of first and/or second factor authenticators (e.g., OTP, FIDO, TOKEN). The IDP Login flow allows access to an application after authenticating using an external identity provider. The Passkey Login flow allows access to an application using a Passkey/FIDO token.
Identity Providers
Identity providers define external OpenID Connect (OIDC) or SAML identity providers that can be used for user authentication and user verification purposes. The identity providers APIs provide management of identity providers using the administration API.
Directories
These APIs provide directory related information using the administration API.
Tenants
For service provider accounts, the tenant APIs provide management of their child tenants as well as management of entitlements for those tenants. These APIs are only available for accounts that are service providers.
Account Info
The account info APIs provide functionality to fetch and modify account related information such as the company name and the license acknowledged flag.
ActiveSync Access
These APIs facilitate management of Exchange ActiveSync Devices available on your Microsoft Office 365 account.
Entitlements
These APIs are used by child tenants to retrieve their own entitlement information.
Organizations
An organization is a collection of users given access to applications in a business-to-business configuration using a single Identity as a Service account. These APIs provide management of organizations as well as management of user membership to organizations.
Webhooks
These APIs provide management of webhooks.
Examples
The following are examples of Admin API calls that can be used to perform administrative actions. The examples below are not an exhaustive list of possible Admin API actions.
Important: You must execute the Authentication (Admin API) call before executing any other Admin API calls. The Authentication (Admin API) call generates a token value that must be included in every other request to be successful.
Authentication (Admin API)
To perform this action, the first step is to submit a POST request to the Admin application. This is the Admin application created on your Identity as a Service account. The URL address of the Admin application includes your Identity as a Service account URL. The format of the URL is:
https://<domainname>.<region>.trustedauth.com/api/web/v1/adminapi/authenticate
For example:
https://example.us.trustedauth.com/api/web/v1/adminapi/authenticate
The body of this request should contain the JSON object with an Application ID and Shared Secret. This JSON file was generated during creation of Admin Application on Identity as a Service. For example:
{
"applicationId": "d3737e0f-4d8e-431c-b1d8-cd17ad4d633d",
"sharedSecret": "randomSharedSecret"
}
An API response is received if the call is successful . For example:
{
"authToken": "GLb6JWz966gCayVNw4lZSSKV6W3PGgsJZ4CagZjoZNMaa2Me7F5OX+CKOVx8sOXsBEdLemVEruixXoaVsjQc1j+GPBy5Qn+KlilA9GXrSEQujsmfiJono3Gta7Uc8b3VUkEBvU193UqWPtmW1NXsSnPV2Z9B2AjZT17zNlHAyOvFpOXTI5bkmj6f2cKses6cBem5kLSbGHH9lHBv4JvXBjNxtPf7urAUkFn8cJariZyb0/q/AYqYL9do8nFrPFmSCTjYeNmxuWm5CACRi17K5XSyhZpu979b3i7MQEeOq1Pfjw7WzdKfrSvLJg/qgYeLD4aSOrQu4HAixZSFBmW9RGDxlo0J0Y1uAAy4lR57yG3p6E8H6OcV3Vakso4CT8yHAFH8xmdsUXXfyv9v+hr5QKh+7iVYro8tjjByRzj6XXAOx0vDO2yhpOd4migv33aWlFEhbgxIzNseJ8je6wauST0O+hJ5kKjl5yLBXS3iKhZJZMG2FNcU5pbD7SnUh79OWoCuOsehOM2pDFDPnMEms5ri/y0yaKIZmtz9Poy6KH1BDd+645+xX8iqW4IeqJ3zW8RZtnJgzAkUFeCjuDtbvotIcR45p8ibXF0GWLFAbxzvc5daf21bBV29A33C7mFoX4id44BZJ6OC8fztmthRzR2l0uP04STG0dgRRTNgZpoqKiMczwbOVNDv7ZQeSf/Kh3n2S1O8SZXHZT+zUvPwCLg9mnhOTYEqPjoMlqTZycttFYv3D4hKbU7NzYmFdtGYreaI2rNNue7aOzn+J8BN0j3+ZHkhimfO/ZfhF89Bn02IRzDER1ENdcwBSO8frWeAR+nCy0m4Eg==",
"expirationTime": "2018-05-28T19:07:50.328+0000",
"creationTime": "2018-05-28T18:52:50.329+0000"
}
You must include the auth token value displayed in this response in subsequent API calls. Without it, other Admin API calls will fail.
An error code is displayed if the call is unsuccessful. A different error code is displayed for each type of error.
Users
Create A User
Submit a POST request to create a User on your account. The format of the URL is:
https://<domainname>.<region>.trustedauth.com/api/web/v3/users
An Authorization header field must be included in the header section of this request. The Authorization header stores the value received as "token" in the authentication request. The Authorization header can be sent with or without a type value of "Bearer". For example:
Authorization: Bearer <token>
or
Authorization: <token>
The body of this request must contain all the fields mentioned in the example below that are configured as mandatory:
{
"firstName": "john",
"lastName": "smith",
"email": "johnsmith@organization.com",
"userId": "john",
"mobile": "+16138561234",
"phone": "+161385699876",
"locale": "",
"state": "ACTIVE",
"externaId": null,
"externalSource": null,
"userAttributeValues": [
],
"userAliases": [
{
"value": "johnny",
"type": "CUSTOM"
}
]
}
In this example, all the required input parameters have been provided. The request would succeed and generate a response that includes all the details of the created user. For example:
{
"id": "2c422a2f-e8ae-4af8-8b03-e1ce0ddde0b0",
"userId": "john",
"firstName": "john",
"lastName": "smith",
"email": "johnsmith@organization.com",
"mobile": "+16138561234",
"phone": "+161385699876",
"locale": null,
"state": "ACTIVE",
"externalId": null,
"externalSource": null,
"migrated": null,
"locked": false,
"lockoutExpiry": null,
"otpCreateTime": null,
"grids": [],
"tokens": [
{
"id": "9a2edcc5-46f0-4fff-89b1-13c0f73e1a5c",
"type": "ENTRUST_SOFT_TOKEN",
"serialNumber": "62461-69384",
"loadDate": "2018-05-29T19:12:54.000+0000",
"lastUsedDate": null,
"state": "ACTIVATING",
"platform": null,
"registeredForTransactions": false,
"name": null,
"allowedActions": [
"REACTIVATE",
"ACTIVATE_COMPLETE",
"DELETE"
],
"description": null,
"userId": null
}
],
"smartCredentials": [],
"tempAccessCode": null,
"userAttributeValues": [],
"userAliases": [
{
"id": "43422a2f-e8ae-4af8-8b03-e1ce0ddde0b0",
"userId": "c633a710-70bd-411e-86be-e1898f1b19f5",
"value": "johnny",
"type": "CUSTOM"
},
{
"id": "2c422a2f-e8ae-4af8-8b03-e1ce0ddde0b0",
"userId": "c633a710-70bd-411e-86be-e1898f1b19f5",
"value": "john",
"type": "USERID"
}
],
"groups": [],
"type": "MGMT_UI"
}
Get a User by UserID
Submit a POST request to retrieve user details for a particular User ID. The format of the URL is:
https://<domainname>.<region>.trustedauth.com/api/web/v3/users/userid
An Authorization header field must be included in the header section of this request. The Authorization header stores the value received as "token" in the authentication request. The Authorization header can be sent with or without a type value of "Bearer". For example:
Authorization: Bearer <token>
or
Authorization: <token>
The body of this request must contain UserID. For example:
{
"userId": "John"
}
In this example, all the required input parameters have been provided. The request would succeed and generate a response that includes the user's information. For example:
{
"id": "2c422a2f-e8ae-4af8-8b03-e1ce0ddde0b0",
"userId": "john",
"firstName": "john",
"lastName": "smith",
"email": "johnsmith@organization.com",
"mobile": "+16138561234",
"phone": "+161385699876",
"locale": null,
"state": "ACTIVE",
"externalId": null,
"externalSource": null,
"migrated": null,
"locked": false,
"lockoutExpiry": null,
"otpCreateTime": null,
"grids": [],
"tokens": [
{
"id": "9a2edcc5-46f0-4fff-89b1-13c0f73e1a5c",
"type": "ENTRUST_SOFT_TOKEN",
"serialNumber": "62461-69384",
"loadDate": "2018-05-29T19:12:54.000+0000",
"lastUsedDate": null,
"state": "ACTIVATING",
"platform": null,
"registeredForTransactions": false,
"name": null,
"allowedActions": [
"REACTIVATE",
"ACTIVATE_COMPLETE",
"DELETE"
],
"description": null,
"userId": null
}
],
"smartCredentials": [],
"tempAccessCode": null,
"userAttributeValues": [],
"userAliases": [
{
"id": "43422a2f-e8ae-4af8-8b03-e1ce0ddde0b0",
"userId": "c633a710-70bd-411e-86be-e1898f1b19f5",
"value": "johnny",
"type": "CUSTOM"
},
{
"id": "2c422a2f-e8ae-4af8-8b03-e1ce0ddde0b0",
"userId": "c633a710-70bd-411e-86be-e1898f1b19f5",
"value": "john",
"type": "USERID"
}
],
"groups": [],
"type": "MGMT_UI"
}
Grids
Create a Grid
Submit a POST request to create a new Grid Card and assign it to a user. You must include the UUID of the user that you want to assign a Grid Card in the API request. The format of the URL is:
https://<domainname>.<region>.trustedauth.com/api/web/v2/users/{userid}/grids
For example:
https://example.us.trustedauth.com/api/web/v2/users/2c422a2f-e8ae-4af8-8b03-e1ce0ddde0b0/grids
An Authorization header field must be included in the header section of this request. The Authorization header stores the value received as "token" in the authentication request. The Authorization header can be sent with or without a type value of "Bearer". For example:
Authorization: Bearer <token>
or
Authorization: <token>
In this example, all the required input parameters have been provided. The request would succeed and generate a response that includes the desired Grid Card information. For example:
{
"id": "6c5ad3b4-888c-4d3b-88f2-8ab71ae4f917",
"serialNumber": 2,
"createDate": "2018-05-29T19:48:24.249+0000",
"assignDate": null,
"expiryDate": null,
"expired": false,
"lastUsedDate": null,
"state": "ACTIVE",
"gridContents": [
[
"TP",
"0M",
"P8",
"KW",
"3D",
"KR",
"M1",
"W0",
"TJ",
"F4"
],
[
"9M",
"MV",
"88",
"DX",
"H3",
"DV",
"44",
"PW",
"V1",
"CX"
],
[
"F2",
"FE",
"0Q",
"XN",
"CD",
"36",
"MQ",
"PN",
"WF",
"DD"
],
[
"WN",
"9F",
"J4",
"TF",
"7J",
"W4",
"7M",
"9Q",
"1H",
"W5"
],
[
"QM",
"21",
"VQ",
"39",
"1N",
"EV",
"PT",
"P4",
"28",
"WY"
]
],
"allowedActions": [
"DELETE",
"DISABLE"
],
"userId": "2c422a2f-e8ae-4af8-8b03-e1ce0ddde0b0",
"userName": "john"
}
Get a Grid by Id
Submit a GET request to display a Grid Card's details. You must include the Grid Card's ID string in the request. The ID is required to identify which Grid Card's details to display. The format of the request URL is:
https://customer.region.trustedauth.com/api/web/v2/grids/{gridid}
For example:
https://example.us.trustedauth.com/api/web/v2/grids/6c5ad3b4-888c-4d3b-88f2-8ab71ae4f917
An Authorization header field must be included in the header section of this request. The Authorization header stores the value received as "token" in the authentication request. The Authorization header can be sent with or without a type value of "Bearer". For example:
Authorization: Bearer <token>
or
Authorization: <token>
In this example, all the required input parameters have been provided. The request would succeed and generate a response that includes Grid Card details. For example:
{
"id": "6c5ad3b4-888c-4d3b-88f2-8ab71ae4f917",
"serialNumber": 2,
"createDate": "2018-05-29T19:48:24.000+0000",
"assignDate": null,
"expiryDate": null,
"expired": false,
"lastUsedDate": null,
"state": "ACTIVE",
"gridContents": [
[
"TP",
"0M",
"P8",
"KW",
"3D",
"KR",
"M1",
"W0",
"TJ",
"F4"
],
[
"9M",
"MV",
"88",
"DX",
"H3",
"DV",
"44",
"PW",
"V1",
"CX"
],
[
"F2",
"FE",
"0Q",
"XN",
"CD",
"36",
"MQ",
"PN",
"WF",
"DD"
],
[
"WN",
"9F",
"J4",
"TF",
"7J",
"W4",
"7M",
"9Q",
"1H",
"W5"
],
[
"QM",
"21",
"VQ",
"39",
"1N",
"EV",
"PT",
"P4",
"28",
"WY"
]
],
"allowedActions": [
"DELETE",
"DISABLE"
],
"userId": "2c422a2f-e8ae-4af8-8b03-e1ce0ddde0b0",
"userName": "john"
}
Authentication
- API Key: AdminAPIAuthentication
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | Authorization |
Contact Entrust Identity as a Service: support@entrust.com