Trusona Service

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

What’s in this doc

Overview

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

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.

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.

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

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.

Convert the hmac signature to hex

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

b1cd445485932340fd2cd03179174ac52053b96e924c9573da6ac6898171c827

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.

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>

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

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

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.

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

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>

Version information

Version : 2.0.0

Contact information

Contact Email : engineering@trusona.com

License information

License : PROPRIETARY Terms of service : null

URI scheme

Host : api.trusona.net Schemes : HTTPS

Tags

  • device : Access to Devices
  • user_device : Access to User Device Bindings

Paths

Create a Trusonafication (legacy endpoint)

POST /api/v1/verifications

Parameters

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

Responses

HTTP Code Description Schema
201 Successfully created the Trusonafication No Content

Tags

  • verification

Look up a Trusonafication (legacy endpoint)

GET /api/v1/verifications/{trusonaficationId}

Parameters

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

Responses

HTTP Code Description Schema
200 Succesfully found the Trusonafication Verification

Tags

  • verification

Create a new device

POST /api/v2/devices

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

Responses

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • device

Example HTTP request

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"
  },
  "device_platform" : "android",
  "bundle_id" : "com.trusona.TruBank"
}

Example HTTP response

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

Gets a device by identifier

GET /api/v2/devices/{identifier}

Description

Returns the device information associated with the provided identifier

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

Responses

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

Produces

  • application/json

Tags

  • device

Example HTTP response

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

Register an identity document with Trusona

POST /api/v2/identity_documents

Description

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

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

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • identity_document

Example HTTP response

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

Get the identity documents for a user

GET /api/v2/identity_documents

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

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

Responses

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • identity_document

Example HTTP response

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

Get a specific identity document

GET /api/v2/identity_documents/{id}

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

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

Responses

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • identity_document

Example HTTP response

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

Create a new pairing for a Trucode

POST /api/v2/paired_trucodes

Description

Creates a new Trucode pairing with an identifier

Parameters

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

pairedTrucode

Name Schema
identifier
required
string
payload
required
string

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • trucode

Get the result of a paired Trucode

GET /api/v2/paired_trucodes/{id}

Description

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

Parameters

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

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

Produces

  • application/json

Tags

  • trucode

Create a new Trucode

POST /api/v2/trucodes

Description

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

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

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • trucode

Get the status of a Trucode

GET /api/v2/trucodes/{id}

Description

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

Parameters

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

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

Produces

  • application/json

Tags

  • trucode

Accept a Trusonafication

POST /api/v2/trusonafication_responses

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

Responses

HTTP Code Description Schema
201 Created No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • trusonafication_response

Reject a Trusonafication

DELETE /api/v2/trusonafication_responses/{id}

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

Responses

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • trusonafication_response

Create a new trusonafication

POST /api/v2/trusonafications

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
custom_fields
optional
Key-value pairs of abitrary data made available within the Trusonafication, which can be inspected in the mobile SDK when processing the trusonafication Map<string,?>
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

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • trusonafication

Example HTTP response

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

Get Trusonafication history for a user

GET /api/v2/trusonafications

Parameters

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

Responses

HTTP Code Description Schema
200 OK TrusonaficationArray

Produces

  • application/json

Tags

  • trusonafication

Get next Trusonafication to handle

GET /api/v2/trusonafications/next

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

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

Produces

  • application/json

Tags

  • trusonafication

Example HTTP response

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

Get an existing trusonafication

GET /api/v2/trusonafications/{id}

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

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

Produces

  • application/json

Tags

  • trusonafication

Example HTTP response

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

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

POST /api/v2/user_bindings

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.

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

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

Produces

  • application/json

Tags

  • user_binding

Create a Device+User Binding

POST /api/v2/user_devices

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

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • user_device

Example HTTP response

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

Update a Device+User Binding

PATCH /api/v2/user_devices/{id}

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

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • user_device

Example HTTP response

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

Create a new user identifier entry

POST /api/v2/user_identifiers

Parameters

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

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

Tags

  • user_identifier

Look up a user identifier

GET /api/v2/user_identifiers/{identifier}

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

Responses

HTTP Code Description Schema
200 Succesfully found the Trusona user UserIdentifier

Tags

  • user_identifier

Deletes a user

DELETE /api/v2/users/{userIdentifier}

Description

Deactivates all of the user’s devices

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

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

Tags

  • user

Save an identity document for a user

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

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.

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

Responses

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

Consumes

  • application/json

Produces

  • application/json

Tags

  • identity_document

Get keys used to sign device identifier JWTs

GET /jwks

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

Definitions

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)

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

Device

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

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

DeviceResponse

Name Description Schema
activated_at
optional
The timestamp when the device was activated string (date-time)
is_active
optional
Whether or not the device has been activated 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

Error

Name Schema
description
required
string
error
required
string
message
required
string

ErrorWithFields

Polymorphism : Composition

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

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)

JsonWebKey

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

Name Schema
alg
required
string
kty
required
string

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
Key-value pairs of abitrary data made available within the Trusonafication, which can be inspected in the mobile SDK when processing the trusonafication Map<string,?>
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 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

TrusonaficationArray

Type : < Trusonafication > array

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)

TrusonaficationResult

Name Description Schema
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
Indiciates if the Trusonfication was accepted boolean
user_identifier
optional
DEPRECATED: The user identifier bound to the device that responded to the Trusonafication string

UserDevice

Name Schema
device_identifier
required
string
user_identifier
required
string

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

UserIdentifier

Name Schema
identifier
required
string
trusona_id
required
string

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

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