Authentication Service
ID Proofing Service
Mobile Auth for Browsers Service

Trusona Service

An overview of using Trusona's RESTful Service APIs to create a passwordless authentication experience for your users.

Trusona Engineering
By

1. Overview

The Trusona API - create devices, register users, trusonafy them.

2. HMAC Authentication

Most of the Trusona API services require the request to include an Authorization header with a server token and secret. These can be acquired at the Trusona Developer’s site at https://developers.trusona.com, or by contacting Trusona.

Creating the correct Authorization header requires several steps.

2.1. Compute the body digest

The first step is to take the request body (i.e. the JSON document) and generate a hash of the body. It is important to make sure the body is used after any processing is applied to it, so it is hashed exactly as it is received by the server.

  • Collect the request body into a variable
  • Compute an md5 hash on the body
  • Get the hex representation of the hash.

2.2. Combine the request data

After the body hash is computed, the string to be signed is built. Take each of the following request attributes and join them with a newline character:

  • HTTP method
  • body hash (from the previous step)
  • Value of content type header
  • Value of date header
  • Path of HTTP request

When all of the items are joined together, the final string will look similar to the following:

POST
f23b480041b22431105ea236c8adc3df
application/json
Thu, 03 Jan 2019 17:57:07 GMT
/api/v2/user_devices

2.3. Use the HMAC-SHA256 algorithm to generate a signature

The string computed in the previous step should be passed into an HMAC-SHA256 function, using the server secret you received from Trusona, which will result in a binary signature.

2.4. Convert the hmac signature to hex

The binary signature should be converted into a hex representation, which will look similar to the following:

b1cd445485932340fd2cd03179174ac52053b96e924c9573da6ac6898171c827

2.5. Convert the hex string to base64

The hex string from the previous step should be converted into base64 encoding, resulting in a string similar to the following:

YjFjZDQ0NTQ4NTkzMjM0MGZkMmNkMDMxNzkxNzRhYzUyMDUzYjk2ZTkyNGM5NTczZGE2YWM2ODk4MTcxYzgyNw==

Note that the hex string itself should be encoded, not the binary signature.

2.6. Add base 64 value and token as auth header

Finally, join the server token received from Trusona to the base64 signature with a colon, and add a prefix of TRUSONA, followed by a space. Set this value as the Authorization header on the request. The Authorization header will look similar to the following:

Authorization: TRUSONA <token>:<base64 signature>

3. Device Signature

The API services intended for communication with mobile devices require requests to be signed with the device key generated on the device. The device signature is sent in a request header called X-Device-Sig. Building the device signature requires the following steps:

  • Generate a JWK thumbrint
  • Generate a nonce
  • Combine the two values with a colon
  • Convert to base64
  • Sign the base64 value with the device key
  • Convert the result to base64
  • Combine the unsigned base64 value with the signature
  • Add the result to the X-Device-Sig header

3.1. Compute the JWK Thumbprint

Based on the device key stored on the mobile device, a JWK thumbprint should be computed as outlined in the spec here:

https://tools.ietf.org/html/draft-ietf-jose-jwk-thumbprint-08

3.2. Combine the JWK thumbprint with a nonce

After computing the JWK thumbprint, a nonce (a unique value for one time use) should be generated. It is recommended to use a standard UUID for the nonce.

The two values should be combined together with a colon:

<thumbprint value>:<nonce>

After the two values are combined, the resulting value should be converted to base64.

3.3. Sign the thumbprint/nonce base64 value

The base64 value computed in the previous step should be signed using the device key that was generated on the device. The signature should use SHA256. Once you have the raw signature bytes, they should be converted into base64

3.4. Combine the unsigned thumbprint/nonce with the signature

Once you have the signature, the unsigned base64 value should be combined with the base64 signature value, and the result should be placed in the X-Device-Sig header for the request:

X-Device-Sig: <unsigned thumbrint/nonce base64>.<signature base64>

3.5. Version information

Version : 2.0.0

3.6. Contact information

Contact Email : engineering@trusona.com

3.7. License information

License : PROPRIETARY Terms of service : null

3.8. URI scheme

Host : api.trusona.net Schemes : HTTPS

4. Paths

4.1. Create a Trusonafication (legacy endpoint)

POST /api/v1/verifications

4.1.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using user’s credentials string
Body verification
optional 		  Trusonafication

4.1.2. Responses

HTTP Code Description Schema
201 Successfully created the Trusonafication No Content

4.2. Look up a Trusonafication (legacy endpoint)

GET /api/v1/verifications/{trusonaficationId}

4.2.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using user’s credentials string
Path trusonaficationId
required 		An ID of a Trusonafication string

4.2.2. Responses

HTTP Code Description Schema
200 Succesfully found the Trusonafication Verification

4.3. Create a new device

POST /api/v2/devices

4.3.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC’d request string string
Header X-Device-Sig
required 		Device identifier + nonce signed by the device key pair. The format is: base64(identifier:nonce).base64(sign(base64(identifier:nonce))) string
Body body
required 		Device object to be registered with Trusona Device

4.3.2. Responses

HTTP Code Description Schema
200 OK SyncDeviceResponse
201 Created SyncDeviceResponse
400 Bad Request Error
403 Forbidden - likely failed authentication Error
422 Unprocessable Entity ErrorWithFields
424 Failed Dependency Error
500 Server Error No Content

4.3.3. Consumes

  • application/json

4.3.4. Produces

  • application/json

4.3.5. Example HTTP request

4.3.5.1. Request body
json :
{
  "device_public_key" : {
    "kty" : "EC",
    "crv" : "P-256",
    "x" : "PblIozBGf7KApv5R4MJf5k_3FUvtzDMsMCGKkYDg_ac",
    "y" : "GPaC-XQlMoFg3OoNtZAfuedJZ29ZUFf-eopqLCWGyjs"
  },
  "auth_public_key" : {
    "kty" : "EC",
    "crv" : "P-256",
    "x" : "SRZYipAH_y_-J4Y_3Gwv50ri7TvmgES7gFwN0kGBtPQ",
    "y" : "QUBxJ0eNCVW5LsuR8trxrw4xuf4V0Nti1efEYe3bBSE"
  },
  "secondary_auth_public_key" : {
    "kty" : "EC",
    "crv" : "P-256",
    "d" : "oEYUkERcRDGzkL1oeX7PBmhqu5Gls3E8_Pgde2D6TiM",
    "x" : "hqWM22HA2wZnC08TVdMp4MNVzrjkpqMA5Tc66wMrhSo",
    "y" : "tm_auk_8cWQSPD1s1G1jJO7Btmg8H_xnBFcx4CtXRaU"
  },
  "device_platform" : "android",
  "bundle_id" : "com.trusona.TruBank"
}

4.3.6. Example HTTP response

4.3.6.1. Response 400
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.3.6.2. Response 403
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.3.6.3. Response 424
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}

4.4. Gets a device by identifier

GET /api/v2/devices/{identifier}

4.4.1. Description

Returns the device information associated with the provided identifier

4.4.2. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using RP’s SDK server credentials string
Path identifier
required 		The identifier of the device to retrieve string

4.4.3. Responses

HTTP Code Description Schema
200 OK DeviceResponse
403 Forbidden - failed authentication Error
404 Not Found Error
500 Server Error No Content

4.4.4. Produces

  • application/json

4.4.5. Example HTTP response

4.4.5.1. Response 403
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.4.5.2. Response 404
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}

4.5. Update a device

PATCH /api/v2/devices/{identifier}

4.5.1. Description

Activate or deactivate a device

4.5.2. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using RP’s SDK server credentials string
Path identifier
required 		The identifier of the device to update string
Body body
required 		  body

body

Name Description Schema
active
required 		Set to true to activate boolean

4.5.3. Responses

HTTP Code Description Schema
200 OK DeviceResponse
403 Forbidden - failed authentication Error
404 Not Found Error
500 Server Error No Content

4.5.4. Produces

  • application/json

4.5.5. Example HTTP response

4.5.5.1. Response 403
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.5.5.2. Response 404
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}

4.6. Register an identity document with Trusona

POST /api/v2/identity_documents

4.6.1. Description

Registers an identity document. Based on RP configuration the identity document may also get verified. Replaces existing identity document.

4.6.2. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC’d request string string
Header X-Device-Sig
required 		Device identifier + nonce signed by the device key pair. The format is: base64(identifier:nonce).base64(sign(base64(identifier:nonce))) string
Body body
required 		Identity document object to be registered with Trusona IdentityDocument

4.6.3. Responses

HTTP Code Description Schema
201 Created IdentityDocument
400 Bad Request Error
403 Forbidden - likely failed authentication Error
422 Unprocessable Entity ErrorWithFields
424 Failed Dependency Error
500 Server Error No Content

4.6.4. Consumes

  • application/json

4.6.5. Produces

  • application/json

4.6.6. Example HTTP response

4.6.6.1. Response 400
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.6.6.2. Response 403
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.6.6.3. Response 424
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}

4.7. Get the identity documents for a user

GET /api/v2/identity_documents

4.7.1. Description

Get the identity documents that have been registered with Trusona for a given user. Trusona does not store any of the personal information of the user, so the returned value is the hash of the scanned document, the type of document, and the verification status

4.7.2. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using RP’s SDK server credentials string
Query user_identifier
required 		The user’s identifier to find identity documents for string

4.7.3. Responses

HTTP Code Description Schema
200 OK < IdentityDocument > array
400 Bad Request Error
403 Forbidden - likely failed authentication Error
500 Server Error No Content

4.7.4. Consumes

  • application/json

4.7.5. Produces

  • application/json

4.7.6. Example HTTP response

4.7.6.1. Response 400
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.7.6.2. Response 403
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}

4.8. Get a specific identity document

GET /api/v2/identity_documents/{id}

4.8.1. Description

Gets an identity document that has been registered with Trusona with the given ID. Trusona does not store any of the personal information of the user, so the returned value is the hash of the scanned document, the type of document, and the verification status

4.8.2. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using RP’s SDK server credentials string
Path id
required 		The ID of the identity document to get string

4.8.3. Responses

HTTP Code Description Schema
200 OK IdentityDocument
403 Forbidden - likely failed authentication Error
404 Not Found Error
500 Server Error No Content

4.8.4. Consumes

  • application/json

4.8.5. Produces

  • application/json

4.8.6. Example HTTP response

4.8.6.1. Response 403
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.8.6.2. Response 404
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}

4.9. Create a new pairing for a Trucode

POST /api/v2/paired_trucodes

4.9.1. Description

Creates a new Trucode pairing with an identifier

4.9.2. Parameters

Type Name Description Schema
Body pairedTrucode
required 		The details of the pairing pairedTrucode

pairedTrucode

Name Schema
identifier
required 		string
payload
required 		string

4.9.3. Responses

HTTP Code Description Schema
201 Created No Content
400 Bad Request No Content
422 Unprocessable Entity No Content
424 Failed Dependency No Content
500 Server Error No Content

4.9.4. Consumes

  • application/json

4.9.5. Produces

  • application/json

4.10. Get the result of a paired Trucode

GET /api/v2/paired_trucodes/{id}

4.10.1. Description

Gets the result of a paired Trucode to get the identifier it was paired with

4.10.2. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC’d request string string
Path id
required 		The ID of the Trucode string

4.10.3. Responses

HTTP Code Description Schema
200 OK Response 200
404 Returned when the TruCode has not been found, has not been paired yet, or has already been retrieved No Content
500 Server Error No Content

Response 200

Name Schema
id
required 		string
identifier
required 		string

4.10.4. Produces

  • application/json

4.11. Create a new Trucode

POST /api/v2/trucodes

4.11.1. Description

Creates a new Trucode that can be scanned by a Trusona device to discover what device was present

4.11.2. Parameters

Type Name Description Schema
Body trucode
required 		The details of the Trucode to be created trucode

trucode

Name Schema
relying_party_id
required 		string

4.11.3. Responses

HTTP Code Description Schema
201 Created Response 201
400 Bad Request No Content
403 Forbidden No Content
422 Unprocessable Entity No Content
500 Server Error No Content

Response 201

Name Schema
id
required 		string
payload
required 		string

4.11.4. Consumes

  • application/json

4.11.5. Produces

  • application/json

4.12. Get the status of a Trucode

GET /api/v2/trucodes/{id}

4.12.1. Description

Gets the status of a Trucode to see whether or not it has been paired

4.12.2. Parameters

Type Name Description Schema
Path id
required 		The ID of the Trucode string

4.12.3. Responses

HTTP Code Description Schema
200 OK Response 200
404 Not Found No Content
500 Server Error No Content

Response 200

Name Schema
id
required 		string
paired
required 		boolean

4.12.4. Produces

  • application/json

4.13. Accept a Trusonafication

POST /api/v2/trusonafication_responses

4.13.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using SDK client credentials string
Header X-Device-Sig
required 		Device identifier + nonce signed by the device key pair. The format is: base64(identifier:nonce).base64(sign(base64(identifier:nonce))) string
Body body
required 		The response to the Trusonafication that was issued body

body

Name Description Schema
payloads
required 		A list of payload strings where the payload string format is base64(payload_json).base64(sign(payload_json)). Valid payload JSON formats are DeviceArPayload, UserPresencePayload, and AAMVALicensePayload < string > array

4.13.2. Responses

HTTP Code Description Schema
201 Created No Content

4.13.3. Consumes

  • application/json

4.13.4. Produces

  • application/json

4.14. Reject a Trusonafication

DELETE /api/v2/trusonafication_responses/{id}

4.14.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using SDK client credentials string
Header X-Device-Sig
required 		Device identifier + nonce signed by the device key pair. The format is: base64(identifier:nonce).base64(sign(base64(identifier:nonce))) string
Path id
required 		The ID of the Trusonafication to be rejected string

4.14.2. Responses

HTTP Code Description Schema
204 The Trusonafication was successfully rejected No Content
422 Rejecting Trusonafication failed No Content

4.14.3. Consumes

  • application/json

4.14.4. Produces

  • application/json

4.15. Create a new trusonafication

POST /api/v2/trusonafications

4.15.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC’d request string string
Body body
required 		The Trusonafication object that needs to be created body

body

Name Description Schema
action
required 		The Trusonafication action string
callback_url
optional 		A HTTPS URL to POST to when the trusonafication has been completed (accepted, rejected, or expired). The body will be the trusonafication object along with a Signed JWT in the jwt field.
NOTE - The URL should include a randomized segment so it cannot be guessed and abused by third-parties e.g. https://your.domain.com/completed_authentications/f8abe61d-4e51-493f-97b1-464c157624f2.		 string
custom_fields
optional 		Arbitrary properties that can be added to the Trusonafication. In the Trusona app, these properties are not used. In an app using the Trusona mobile SDKs, they are available to the app and can be used in the UI. object
desired_level
required 		The desired level for the Trusonafication (1=EN, 2=ES, 3=EX)
Minimum value : 1
Maximum value : 3 		integer
device_identifier
optional 		The identifier of the device registered with Trusona string
email
optional 		The email for the user, previously registered string
expires_at
optional 		The timestamp when the Trusonafication expires string (date-time)
prompt
optional 		Whether or not to prompt the user with a dialog about what the RP wants them to do and requires the user to explicitly accept or reject the action
Default : true 		boolean
resource
required 		The Trusonafication resource string
show_identity_document
optional 		Whether or not to request the user to scan a registered identity document
Default : false 		boolean
trusona_id
optional 		The Trusona ID of the user string
user_identifier
optional 		The user identifier that was bound to at least one device in Trusona string
user_presence
optional 		Whether or not to verify the user’s presence via OS level security (uses pin or biometrics or whatever the user has setup on their device)
Default : true 		boolean

4.15.2. Responses

HTTP Code Description Schema
201 Created Trusonafication
400 Bad Request Error
403 Forbidden - likely failed authentication Error
422 Unprocessable Entity Response 422
500 Server Error No Content

Response 422

Name Description Schema
errors
optional 		  < string > array
message
optional 		Short description of error condition string

4.15.3. Consumes

  • application/json

4.15.4. Produces

  • application/json

4.15.5. Example HTTP response

4.15.5.1. Response 400
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.15.5.2. Response 403
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}

4.16. Get next Trusonafication to handle

GET /api/v2/trusonafications/next

4.16.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC’d request string string
Header X-Device-Sig
required 		Device identifier + nonce signed by the device key pair. The format is: base64(identifier:nonce).base64(sign(base64(identifier:nonce))) string

4.16.2. Responses

HTTP Code Description Schema
200 OK Trusonafication
204 No pending Trusonafications No Content
403 Forbidden - likely failed authentication Error
500 Server Error No Content

4.16.3. Produces

  • application/json

4.16.4. Example HTTP response

4.16.4.1. Response 403
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}

4.17. Get an existing trusonafication

GET /api/v2/trusonafications/{id}

4.17.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC’d request string string
Header X-Device-Sig
required 		Device identifier + nonce signed by the device key pair. The format is: base64(identifier:nonce).base64(sign(base64(identifier:nonce))) string
Path id
required 		The record ID of the Trusonafication string

4.17.2. Responses

HTTP Code Description Schema
200 OK Trusonafication
403 Forbidden - likely failed authentication Error
404 Not Found - the record does not exist No Content
500 Server Error No Content

4.17.3. Produces

  • application/json

4.17.4. Example HTTP response

4.17.4.1. Response 403
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}

4.18. Cancel an IN_PROGRESS Trusonafication

DELETE /api/v2/trusonafications/{id}

4.18.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using SDK client credentials string
Path id
required 		The ID of the Trusonafication to be canceled string

4.18.2. Responses

HTTP Code Description Schema
204 The Trusonafication was successfully canceled No Content
403 Authentication error No Content
422 Canceling the Trusonafication failed No Content

4.18.3. Consumes

  • application/json

4.18.4. Produces

  • application/json

4.19. Create a binding between a user and an RP identifier, from a scanned TruCode

POST /api/v2/user_bindings

4.19.1. Description

After you present a TruCode to a user running the Trusona app or a custom app with the Trusona SDK, and the user has scanned the TruCode, this endpoint can be called to create a binding between the user who scanned the TruCode and an identifier known in your systems.

This identifier can later be used to create a Trusonafication to authenticate a user.

It is recommended that you send a Trusonafication to the user in between when they scan the TruCode and when you create the binding, to confirm the user’s intent and to avoid the user getting stuck on the spinner that appears after scanning a TruCode.

4.19.2. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC’d request string string
Body UserBindingRequest
required 		  UserBindingRequest

UserBindingRequest

Name Description Schema
trucode_id
required 		The ID of a TruCode that has been paired to a device string
user_identifier
required 		An identifier that is known to the Relying Party which identifies the user that should be bound string

4.19.3. Responses

HTTP Code Description Schema
201 The binding was successfully created No Content
409 The user that scanned the TruCode is already bound to an identifier for this Relying Party No Content
422 The request was invalid No Content
424 The TruCode was not paired or a user could not be found associated with the TruCode No Content

4.19.4. Produces

  • application/json

4.20. Create a Device+User Binding

POST /api/v2/user_devices

4.20.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC’d request string string
Body body
required 		Device+User Binding object that needs to be added UserDevice

4.20.2. Responses

HTTP Code Description Schema
201 Created UserDeviceResponse
400 Bad Request Error
403 Forbidden - likely failed authentication Error
409 Conflict Error
422 Unprocessable Entity ErrorWithFields
424 Failed Dependency Error
500 Server Error No Content

4.20.3. Consumes

  • application/json

4.20.4. Produces

  • application/json

4.20.5. Example HTTP response

4.20.5.1. Response 400
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.20.5.2. Response 403
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.20.5.3. Response 409
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.20.5.4. Response 424
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}

4.21. Update a Device+User Binding

PATCH /api/v2/user_devices/{id}

4.21.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC’d request string string
Path id
required 		The record ID of the UserDevice string
Body body
required 		fields to update for the UserDevice body

body

Name Description Schema
active
required 		desired activation state for device boolean

4.21.2. Responses

HTTP Code Description Schema
200 OK UserDeviceResponse
400 Bad Request Error
403 Forbidden - likely failed authentication Error
404 Not Found No Content
500 Server Error No Content

4.21.3. Consumes

  • application/json

4.21.4. Produces

  • application/json

4.21.5. Example HTTP response

4.21.5.1. Response 400
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}
4.21.5.2. Response 403
json :
{
  "error" : "Error occurred",
  "message" : "Could not perform requested action",
  "description" : "The specific reason the action could not be performed"
}

4.22. Create a new user identifier entry

POST /api/v2/user_identifiers

4.22.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using RP’s SDK server credentials string
Body user_identifier
optional 		  UserIdentifier

4.22.2. Responses

HTTP Code Description Schema
204 The user identifier was created No Content
409 The user already has a user identifier associated No Content
422 Validation failed No Content
424 The user wasn’t found No Content

4.23. Look up a user identifier

GET /api/v2/user_identifiers/{identifier}

4.23.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using RP’s SDK server credentials string
Path identifier
required 		The identifier that was previously associated with the user string

4.23.2. Responses

HTTP Code Description Schema
200 Succesfully found the Trusona user UserIdentifier

4.24. Deletes a user

DELETE /api/v2/users/{userIdentifier}

4.24.1. Description

Deactivates all of the user’s devices

4.24.2. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using RP’s SDK server credentials string
Path userIdentifier
required 		The userIdentifier known to the RP to be deleted string

4.24.3. Responses

HTTP Code Description Schema
204 The delete was successful No Content
403 RP’s credentials were invalid No Content
404 The user was not found No Content
500 An internal error occurred No Content

4.25. Look up Accounts by Trusona ID

GET /api/v2/integrations/{integration}/accounts?trusonaId={trusonaId}

4.25.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using RP’s SDK server credentials string
Path integration
required 		The integration identifier string
Query trusonaId
required 		The public Trusona ID of the user string

4.25.2. Responses

HTTP Code Description Schema
200 Succesfully queried for the Trusona Account(s) List of Accounts
403 RP’s credentials were invalid No Content

4.26. Look up Accounts by Identifier

GET /api/v2/integrations/{integration}/accounts?identifier={identifier}

4.26.1. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using RP’s SDK server credentials string
Path integration
required 		The integration identifier string
Query identifier
required 		The account identifier of the user string

4.26.2. Responses

HTTP Code Description Schema
200 Succesfully queried for the Trusona Account(s) List of Accounts
403 RP’s credentials were invalid No Content

4.27. Deletes a user

DELETE /api/v2/users/{userIdentifier}

4.27.1. Description

Deactivates all of the user’s devices

4.27.2. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using RP’s SDK server credentials string
Path userIdentifier
required 		The userIdentifier known to the RP to be deleted string

4.27.3. Responses

HTTP Code Description Schema
204 The delete was successful No Content
403 RP’s credentials were invalid No Content
404 The user was not found No Content
500 An internal error occurred No Content

4.28. Save an identity document for a user

POST /api/v2/users/{userIdentifier}/identity_document

4.28.1. Description

This call can be used by an RP to store an identity document for a specific user. The user identifier field is used to look up the user. It should match a user identifier in the bindings table.

4.28.2. Parameters

Type Name Description Schema
Header Authorization
required 		HMAC authorization using RP’s SDK server credentials string
Path userIdentifier
required 		A user identifier for the user string

4.28.3. Responses

HTTP Code Description Schema
201 Returned when the document was successfully added IdentityDocument
422 When the request is invalid No Content

4.28.4. Consumes

  • application/json

4.28.5. Produces

  • application/json

4.29. Get keys used to sign device identifier JWTs

GET /jwks

4.29.1. Responses

HTTP Code Description Schema
200 An array of JWK objects (see https://tools.ietf.org/html/rfc7517) Response 200

Response 200

Name Schema
keys
optional 		< JsonWebKey > array

5. Definitions

5.1. AAMVADriversLicense

Polymorphism : Composition

Name Description Schema
audit_information
optional 		  string
city
optional 		  string
country
optional 		  enum (UNITED_STATES, CANADA, UNKNOWN)
customer_id
optional 		  string
date_of_birth
optional 		  string (date)
document_id
optional 		  string
expiration_date
optional 		  string (date)
eye_color
optional 		  enum (BLACK, BLUE, BROWN, GRAY, GREEN, HAZEL, MAROON, PINK, DICHROMATIC, UNKNOWN)
first_name
optional 		  string
first_name_alias
optional 		  string
first_name_truncation
optional 		  enum (TRUNCATED, NONE, UNKNOWN)
gender
optional 		  enum (MALE, FEMALE, OTHER, UNKNOWN)
hair_color
optional 		  enum (BALD, BLACK, BLOND, BROWN, GREY, RED, SANDY, WHITE, UNKNOWN)
hash
required 		  string
height
optional 		  number (double)
id
optional 		  string
inventory_control_number
optional 		  string
issue_date
optional 		  string (date)
last_name
optional 		  string
last_name_alias
optional 		  string
last_name_truncation
optional 		  enum (TRUNCATED, NONE, UNKNOWN)
middle_name
optional 		  string
middle_name_truncation
optional 		  enum (TRUNCATED, NONE, UNKNOWN)
place_of_birth
optional 		  string
postal_code
optional 		  string
state
optional 		  string
street_address
optional 		  string
street_address_supplement
optional 		  string
suffix
optional 		  enum (JUNIOR, SENIOR, FIRST, SECOND, THIRD, FOURTH, FIFTH, SIXTH, SEVENTH, EIGHTH, NINTH, UNKNOWN)
suffix_alias
optional 		  string
type
optional 		Default : "AAMVA_DRIVERS_LICENSE" enum (AAMVA_DRIVERS_LICENSE)
verification_status
optional 		  enum (UNVERIFIED, UNVERIFIABLE, VERIFIED, FAILED)

5.2. AAMVALicensePayload

Polymorphism : Composition

Name Description Schema
device_identifier
required 		The Trusona identifier for the device string
hash
required 		The device generated hash of the scanned data from a user’s driver’s license string
nonce
required 		Nonce generated at the time of the scan string
scan_height
optional 		Height of box within the camera viewport where the barcode was located number
scan_time
optional 		Time in seconds to scan the document number
scan_width
optional 		Width of box within the camera viewport where the barcode was located number
scan_x
optional 		X position of box within the camera viewport where the barcode was located number
scan_y
optional 		Y position of box within the camera viewport where the barcode was located number
trusonafication_id
required 		The ID of the Trusonafication this is in response to string
type
required 		Default : "aamva_drivers_license" string

5.3. Account

Name Description Schema
id
required 		The Trusona identifier for the Account string
integration_id
required 		The Trusona identifier for the integration string
user_id
required 		The Trusona identifier for the user string
trusona_id
required 		The public Trusona ID of the user string
identifier
required 		The account identifier string
properties
optional 		The properties associated with the Account string
created_at
optional 		The timestamp when the Account was created string (date-time)
updated_at
optional 		The timestamp when the Account was last updated string (date-time)

5.4. Device

Name Schema
auth_public_key
optional 		JsonWebKey
bundle_id
optional 		string
device_platform
required 		enum (android, ios)
device_public_key
required 		JsonWebKey
secondary_auth_public_key
optional 		JsonWebKey

5.5. DeviceArPayload

Polymorphism : Composition

Name Description Schema
accelerometer
optional 		A set of three numbers representing the acceleration of the device in three dimensional space < number > array
checksum
required 		A checksum of the nonce and device identifier formatted as sha256Hex(nonce:device_identifier) string
device_identifier
required 		The Trusona identifier for the device string
gyro
optional 		A set of three numbers representing the rotation of the device around it’s three primary axes < number > array
nonce
required 		A nonce generated on the device prior to sending the payload string
trusonafication_id
required 		The ID of the Trusonafication this is in response to string
type
required 		Default : "device_ar" string

5.6. DeviceResponse

Name Description Schema
activated_at
optional 		The timestamp when the device was activated string (date-time)
active
optional 		Whether or not the device has been activated boolean
is_active
optional 		DEPRECATED: see active field boolean

5.7. Error

Name Schema
description
required 		string
error
required 		string
message
required 		string

5.8. ErrorWithFields

Polymorphism : Composition

Name Schema
description
required 		string
error
required 		string
field_errors
optional 		< string, < string > array > map
message
required 		string

5.9. IdentityDocument

Name Description Schema
hash
required 		  string
id
optional 		  string
type
optional 		Default : "AAMVA_DRIVERS_LICENSE" enum (AAMVA_DRIVERS_LICENSE)
verification_status
optional 		  enum (UNVERIFIED, UNVERIFIABLE, VERIFIED, FAILED)

5.10. JsonWebKey

A JSON Web Key (JWK) as defined by https://tools.ietf.org/html/rfc7517

Name Schema
alg
required 		string
kty
required 		string

5.11. SyncDeviceResponse

Polymorphism : Composition

Name Description Schema
activated_at
optional 		The timestamp when the device was activated string (date-time)
active
optional 		Whether or not the device has been activated boolean
is_active
optional 		DEPRECATED: see active field boolean
jwt
optional 		A Signed JWT containing the device identifier in the sub claim. The JWT can be verified with keys from the /jwks endpoint string

5.12. Trusonafication

Name Description Schema
action
optional 		The Trusonafication action string
created_at
optional 		The timestamp when the Trusonafication was created string (date-time)
custom_fields
optional 		Arbitrary properties that can be added to the Trusonafication. In the Trusona app, these properties are not used. In an app using the Trusona mobile SDKs, they are available to the app and can be used in the UI. object
desired_level
optional 		The desired level for the Trusonafication (1=EN, 2=ES, 3=EX)
Minimum value : 1
Maximum value : 3 		integer
device_identifier
optional 		The device identifier that was used, if any, to determine the user identifier of the Trusonafication string
expires_at
optional 		The timestamp when the Trusonafication expires string (date-time)
id
optional 		The record ID for the Trusonafication string
prompt
optional 		Whether or not to prompt the user with a dialog about what the RP wants them to do and requires the user to explicitly accept or reject the action boolean
relying_party
optional 		The display name for the Relying Party string
resource
optional 		The Trusonafication resource string
result
optional 		  TrusonaficationResult
show_identity_document
optional 		Whether or not to request the user to scan a registered identity document boolean
status
optional 		The status of the Trusonafication enum (INVALID, IN_PROGRESS, REJECTED, ACCEPTED, ACCEPTED_AT_LOWER_LEVEL, ACCEPTED_AT_HIGHER_LEVEL, EXPIRED)
trusona_id
optional 		The public Trusona ID of the user being Trusonafied string
updated_at
optional 		The timestamp when the Trusonafication last updated string (date-time)
user_identifier
optional 		The identifier of the user that has been issued a Trusonafication string
user_presence
optional 		Whether or not to verify the user’s presence via OS level security (uses pin or biometrics or whatever the user has setup on their device) boolean

5.13. TrusonaficationResponsePayload

The base information that all Trusonafication responds payloads share

Name Description Schema
trusonafication_id
required 		The ID of the Trusonafication this is in response to string
type
required 		The type of response payload this is enum (device_ar, user_presence, aamva_drivers_license)

5.14. TrusonaficationResult

Name Description Schema
accepted
optional 		Indiciates if the Trusonfication was accepted boolean
accepted_level
optional 		The level for which the Trusonafication was accepted (1=EN, 2=ES, 3=EX) integer
bound_user_identifier
optional 		The user identifier bound between the user who responded to the Trusonafication and the Relying Party that created the Trusonafication string
device_identifier
optional 		The identifier of the device that responded to the Trusonafication string
id
optional 		The record ID for the TrusonaficationResult string
is_accepted
optional 		DEPRECATED: see accepted field boolean
user_identifier
optional 		DEPRECATED: The user identifier bound to the device that responded to the Trusonafication string

5.15. UserDevice

Name Schema
device_identifier
required 		string
user_identifier
required 		string

5.16. UserDeviceResponse

Polymorphism : Composition

Name Description Schema
activated_at
optional 		Timestamp when the device+user binding was activated string
active
optional 		Indicates if the device+user binding is active.
Default : false 		boolean
device_identifier
required 		  string
id
optional 		The id of the device+user binding that can be use to later activate it. string
user_identifier
required 		  string

5.17. UserIdentifier

Name Schema
identifier
required 		string
trusona_id
required 		string

5.18. UserPresencePayload

Polymorphism : Composition

Name Description Schema
device_identifier
required 		The Trusona identifier for the device string
trusonafication_id
required 		The ID of the Trusonafication this is in response to string
type
required 		Default : "user_presence" string

5.19. Verification

Name Schema
accepted_level
optional 		integer
action
optional 		string
agent_id
optional 		string
callback_url
optional 		string
created_date
optional 		integer
desired_level
optional 		integer
display_name
optional 		string
email
optional 		string
interval
optional 		integer
relying_party_display_name
optional 		string
resource
optional 		string
result_id
optional 		string
status
optional 		string
trusona_id
optional 		string
updated_date
optional 		integer
verification_id
optional 		string

Integrations

Desktop
IAM and SSO
SCIM
PAM
Productivity
VPN
General

Guides

Get started guides
Implementation guides
Users guides

SDKs

Mobile SDKs
Server SDKs
Web SDKs

APIs

Authentication Service
ID Proofing Service
Mobile Auth for Browsers Service

TOTP

Business
E-commerce
Finance
Productivity
Social
Gaming
Other