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 and Token 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 OIDC 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) 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.
ID Proofing
These APIs are used to validate the identity of a person by performing a liveness check using a government-issued identity document, such as a driver's license or a passport, and comparing the document photograph with a self-portrait digital photograph (selfie) taken on a mobile device.
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.
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"
}
ID Proofing
Initiate an ID Proofing Transaction
Submit a POST request to initiate the transaction and obtain the mobile SDK license. You must include a device fingerprint in the request if the service is configured to require it. The format of the request URL is:
https://customer.region.trustedauth.com/api/web/v1/idproofing/init
For example:
https://example.us.trustedauth.com/api/web/v1/idproofing/init
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 should contain firstPartyBlackbox. For example:
{
"clientIp": "1.2.3.4",
"firstPartyBlackbox": "0610Jy4JhpaIbhJOJAyOFS...CpysKGn9rI0cgfvRE="
}
Checking the reputation of a device using a fingerprint is not supported in this release.
In this example, the request would succeed and generate a response that includes the license. For example:
{
"requestId": "0ba70f09-58c8-4a8e-bb87-cf98f4f4c111",
"deviceCheckResult": "ALLOW",
"deviceCheckReason": "",
"deviceCheckDetails": {
"device.alias": "115993746090684075",
"device.bb.age": "9756913",
"device.bb.timestamp": "2019-09-24T13:56:53Z",
"device.firstseen": "2019-09-19T14:01:06.004Z",
"device.flash.storage.enabled": "0",
"device.js.enabled": "0",
"device.new": "0",
"device.os": "IPHONE 12.4.1",
"device.type": "IPHONE",
...
},
"subscriberId": "5f5edd7f-bf52-4c4e-6da3-56a278148bbe",
"subscriberAccount": "example@company.com",
"subscriberPassword": "xyz34@19fdjt&sw2",
...
}
Note the requestId attribute returned. This value must be used in the following interactions with the service.
If a fingerprint is provided (firstPartyBlackbox attribute in the request) and the deviceCheckResult attribute value is DENY, then the transaction cannot be continued.
Upload the Front Side Image of a Document ID
Submit a PUT request to upload the front image of a supported document ID. The format of the request URL is:
https://customer.region.trustedauth.com/api/web/v1/idproofing/<requestId>/image/0
For example:
https://example.us.trustedauth.com/api/web/v1/idproofing/a63b0b66-1d1d-4834-b393-38a52c5e8304/image/0
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 binary image must be submitted in the body of the HTTP request.
If the authentication token has expired and the image is very large, the response sometimes can be a generic Internal Error (500) instead of UNAUTHORIZED (401). To prevent this, it's recommended to submit an OPTIONS request before submitting the PUT request with the image. The OPTIONS request will always return UNAUTHORIZED (401) if the authentication token is expired.
In this example, the image is successfully classified into a well-known document class. For example:
{
"presentationChanged": false,
"documentClass": "DRIVERSLICENSE",
"countryCode": "USA",
"supportedFrontImage": true,
"supportedBackImage": true
}
If the documentClass attribute value is UNKNOWN, then you need to upload a better image to continue.
Upload the Back Side Image of a Document ID
If the response after submitting a valid Front image includes the "supportedBackImage" attribute with value "true", then you can submit a PUT request to upload the back image of a supported document ID. The format of the request URL is:
Note that uploading the back of a document is optional as in some cases all the relevant information is available in the front of the document.
https://customer.region.trustedauth.com/api/web/v1/idproofing/<requestId>/image/1
For example:
https://example.us.trustedauth.com/api/web/v1/idproofing/a63b0b66-1d1d-4834-b393-38a52c5e8304/image/1
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 binary image must be submitted in the body of the HTTP request.
If the authentication token has expired and the image is very large, the response sometimes can be a generic Internal Error (500) instead of UNAUTHORIZED (401). To prevent this, it's recommended to submit an OPTIONS request before submitting the PUT request with the image. The OPTIONS request will always return UNAUTHORIZED (401) if the authentication token is expired.
In this example, the image is successfully classified into a well-known document class. For example:
{
"presentationChanged": false,
"documentClass": "DRIVERSLICENSE",
"countryCode": "USA",
"supportedFrontImage": true,
"supportedBackImage": true
}
If the documentClass attribute value is UNKNOWN, then you need to upload a better image to continue.
Complete an ID Proofing Transaction using a Standard Facial Recognition License
If you are using a Standard Facial Recognition license and the document images uploaded in the previous requests classified correctly, you can now submit a PUT request to upload the selfie that the mobile SDK takes.
https://customer.region.trustedauth.com/api/web/v1/idproofing/<requestId>/completeselfie
For example:
https://example.us.trustedauth.com/api/web/v1/idproofing/a63b0b66-1d1d-4834-b393-38a52c5e8304/completeselfie
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 binary selfie image must be submitted in the body of the HTTP request.
In this example, the selfie matches the document ID photo (faceMatch true) but document ID authentication indicates ATTENTION as one of the tests performed on the document didn't PASS--see documentTestResults:
{
"faceMatch": true,
"faceMatchScore": 84,
"documentAuthenticationResult": "ATTENTION",
"documentDataFields": [
{
"description": "The person's legal, residence, or mailing address",
"name": "Address",
"type": "STRING",
"value": "WICKENBURG AZ 85390"
},
{
"description": "City of the person's legal, residence, or mailing address",
"name": "Address City",
"type": "STRING",
"value": "WICKENBURG"
},
{
"description": "Postal code of the person's address",
"name": "Address Postal Code",
"type": "STRING",
"value": "85390"
},
{
"description": "State of the person's legal, residence, or mailing address",
"name": "Address State",
"type": "STRING",
"value": "AZ"
},
{
"description": "The person's date of birth",
"name": "Birth Date",
"type": "DATETIME",
"value": "1987-03-01T00:00:00Z"
},
{
"description": "The localized version of the document class of the document type",
"name": "Document Class Name",
"type": "STRING",
"value": "Drivers License"
},
{
"description": "A number that identifies a document",
"name": "Document Number",
"type": "STRING",
"value": "D01405395"
},
{
"description": "Date that the document will expire",
"name": "Expiration Date",
"type": "DATETIME",
"value": "2007-01-01T00:00:00Z"
},
{
"description": "The person's first name",
"name": "First Name",
"type": "STRING",
"value": "SAMANTHA"
},
{
"description": "The person's full name (given name plus surname)",
"name": "Full Name",
"type": "STRING",
"value": "SAMANTHA JANE SAMPLE"
},
{
"description": "The person's given name",
"name": "Given Name",
"type": "STRING",
"value": "SAMANTHA JANE"
},
{
"description": "Date that the document was issued",
"name": "Issue Date",
"type": "DATETIME",
"value": "2006-02-23T00:00:00Z"
},
{
"description": "Abbreviated ID code of the state or country that issued the document",
"name": "Issuing State Code",
"type": "STRING",
"value": "AZ"
},
{
"description": "Full name of the state or country that issued the document",
"name": "Issuing State Name",
"type": "STRING",
"value": "Arizona"
},
{
"description": "The person's middle name",
"name": "Middle Name",
"type": "STRING",
"value": "JANE"
},
{
"description": "Indicates whether the document is a form of identification that meets the increased security standards for US state-issued driver's licenses and identification cards under the REAL ID Act",
"name": "REAL ID Compliant",
"type": "STRING",
"value": "False"
},
{
"description": "A single character (translated into M/F from other languages) that identifies the person's gender",
"name": "Sex",
"type": "STRING",
"value": "F"
},
{
"description": "The person's surname or family name",
"name": "Surname",
"type": "STRING",
"value": "SAMPLE"
}
],
"documentTestResults": [
{
"name": "Document Expired",
"description": "Checked if the document is expired.",
"disposition": "The document has expired",
"information": "Verified that the document expiration date does not occur before the current date.",
"actions": "The expiration date on the document may have been misread. Confirm that it is legible and occurs on or after the current date. Also confirm that the current date and time of the host computer is correctly set.",
"result": "ATTENTION"
},
{
"name": "Birth Date Valid",
"description": "Verified that the birth date is valid.",
"disposition": "The birth date is valid",
"information": "Verified that the birth date is valid, in the expected format, and occurs on or before the current date and not outside a reasonable range.",
"actions": "The birth date on the document may have been misread. Confirm that it is legible.",
"result": "PASSED"
},
{
"name": "Document Classification",
"description": "Verified that the type of document is supported and is able to be fully authenticated.",
"disposition": "The document type is supported",
"information": "Verified that the document is recognized as a supported document type and that the type of document can be fully authenticated.",
"actions": "This test may fail if a document cannot be successfully classified as a supported document type. This may occur if the document is fraudulent as some fraudulent documents differ so much from authentic documents that they will not be recognized as that type of document. This may also occur if a valid document is significantly worn or damaged or if the document is of a new or different type that is not yet supported by the library. The document should be examined manually.",
"result": "PASSED"
},
{
"name": "Expiration Date Valid",
"description": "Verified that the expiration date is valid.",
"disposition": "The expiration date is valid",
"information": "Verified that the document expiration date is valid, in the expected format, and occurs after the issue and birth dates.",
"actions": "The expiration date on the document may have been misread. Confirm that it is legible and occurs after the issue and birth dates.",
"result": "PASSED"
},
{
"name": "Issue Date Valid",
"description": "Verified that the issue date is valid.",
"disposition": "The issue date is valid",
"information": "Verified that the document issue date is valid, in the expected format, does not occur in the future, does not occur before the date of birth, and does not occur after the expiration date.",
"actions": "The issue date on the document may have been misread. Confirm that all of the dates are legible, the issue date occurs on or before the current date, and is before the expiration date.",
"result": "PASSED"
},
{
"name": "Visible Pattern",
"description": "Verified the presence of a pattern on the visible image.",
"disposition": "A visible pattern was found",
"information": "Verified that a security feature in the visible spectrum is present and in an expected location on the document.",
"actions": "Check the visible (white) document image to verify the presence of the security feature. Possible reasons this test may fail for a valid document may be that the document was moving during the capture, or the document may be excessively worn or damaged.",
"result": "PASSED"
}
]
}
Complete an ID Proofing Transaction using an Enhanced Facial Recognition License
If you are using an Enhanced Facial Recognition license and the document images uploaded in the previous requests classified correctly, you can now submit a PUT request with the liveness test result that the mobile SDK provides.
https://customer.region.trustedauth.com/api/web/v1/idproofing/<requestId>/complete
For example:
https://example.us.trustedauth.com/api/web/v1/idproofing/a63b0b66-1d1d-4834-b393-38a52c5e8304/complete
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 livenessUserId and livenessToken. For example:
{
"livenessUserId": "919ce7d3-1194-465d-9588-8668b8ac3bac",
"livenessToken": "31706131726336496d655177346e55503279616b69547344446e5258684c7542"
}
The response from this request is identical to the one you can see in the previous section.
Authentication
- API Key: AdminAPIAuthentication
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | Authorization |