The Trusona Service API Reference

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>

API Endpoint
https://api.trusona.net
Contact: engineering@trusona.com
Schemes: https
Version: 2.0.0

device

Access to Devices

Create a new device

POST /api/v2/devices

Device object to be registered with Trusona

Authorization: string
in header

HMAC'd request string

X-Device-Sig: string
in header

Device identifier + nonce signed by the device key pair. The format is: base64(identifier:nonce).base64(sign(base64(identifier:nonce)))

Request Content-Types: application/json
Request Example
{
  "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"
}

OK

201 Created

Created

400 Bad Request

Bad Request

403 Forbidden

Forbidden - likely failed authentication

422 Unprocessable Entity

Unprocessable Entity

424 Failed Dependency

Failed Dependency

500 Internal Server Error

Server Error

Response Content-Types: application/json
Response Example (200 OK)
{
  "is_active": "boolean",
  "activated_at": "string (date-time)"
}
Response Example (201 Created)
{
  "is_active": "boolean",
  "activated_at": "string (date-time)"
}
Response Example (400 Bad Request)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (403 Forbidden)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (422 Unprocessable Entity)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed",
  "field_errors": {
    "field_name1": [
      "may not be blank"
    ],
    "field_name2": [
      "may not be blank",
      "is not a valid email"
    ]
  }
}
Response Example (424 Failed Dependency)
{
  "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}

Returns the device information associated with the provided identifier

Authorization: string
in header

HMAC authorization using RP's SDK server credentials

identifier: string
in path

The identifier of the device to retrieve

OK

403 Forbidden

Forbidden - failed authentication

404 Not Found

Not Found

500 Internal Server Error

Server Error

Response Content-Types: application/json
Response Example (200 OK)
{
  "is_active": "boolean",
  "activated_at": "string (date-time)"
}
Response Example (403 Forbidden)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (404 Not Found)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}

user_device

Access to User Device Bindings

Create a Device+User Binding

POST /api/v2/user_devices

Device+User Binding object that needs to be added

Authorization: string
in header

HMAC'd request string

Request Content-Types: application/json
Request Example
{
  "device_identifier": "string",
  "user_identifier": "string"
}
201 Created

Created

400 Bad Request

Bad Request

403 Forbidden

Forbidden - likely failed authentication

409 Conflict

Conflict

422 Unprocessable Entity

Unprocessable Entity

424 Failed Dependency

Failed Dependency

500 Internal Server Error

Server Error

Response Content-Types: application/json
Response Example (201 Created)
{
  "device_identifier": "string",
  "user_identifier": "string",
  "id": "string",
  "active": "boolean",
  "activated_at": "string"
}
Response Example (400 Bad Request)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (403 Forbidden)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (409 Conflict)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (422 Unprocessable Entity)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed",
  "field_errors": {
    "field_name1": [
      "may not be blank"
    ],
    "field_name2": [
      "may not be blank",
      "is not a valid email"
    ]
  }
}
Response Example (424 Failed Dependency)
{
  "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}

fields to update for the UserDevice

active: boolean

desired activation state for device

Authorization: string
in header

HMAC'd request string

id: string
in path

The record ID of the UserDevice

Request Content-Types: application/json
Request Example
{
  "active": "boolean"
}

OK

400 Bad Request

Bad Request

403 Forbidden

Forbidden - likely failed authentication

404 Not Found

Not Found

500 Internal Server Error

Server Error

Response Content-Types: application/json
Response Example (200 OK)
{
  "device_identifier": "string",
  "user_identifier": "string",
  "id": "string",
  "active": "boolean",
  "activated_at": "string"
}
Response Example (400 Bad Request)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (403 Forbidden)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}

identity_document

Get the identity documents for a user

GET /api/v2/identity_documents

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

Authorization: string
in header

HMAC authorization using RP's SDK server credentials

user_identifier: string
in query

The user's identifier to find identity documents for

OK

400 Bad Request

Bad Request

403 Forbidden

Forbidden - likely failed authentication

500 Internal Server Error

Server Error

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "string",
    "hash": "string",
    "type": "string",
    "verification_status": "string"
  }
]
Response Example (400 Bad Request)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (403 Forbidden)
{
  "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

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

Identity document object to be registered with Trusona

Authorization: string
in header

HMAC'd request string

X-Device-Sig: string
in header

Device identifier + nonce signed by the device key pair. The format is: base64(identifier:nonce).base64(sign(base64(identifier:nonce)))

Request Content-Types: application/json
Request Example
{
  "id": "string",
  "hash": "string",
  "type": "string",
  "verification_status": "string"
}
201 Created

Created

400 Bad Request

Bad Request

403 Forbidden

Forbidden - likely failed authentication

422 Unprocessable Entity

Unprocessable Entity

424 Failed Dependency

Failed Dependency

500 Internal Server Error

Server Error

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "string",
  "hash": "string",
  "type": "string",
  "verification_status": "string"
}
Response Example (400 Bad Request)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (403 Forbidden)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (422 Unprocessable Entity)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed",
  "field_errors": {
    "field_name1": [
      "may not be blank"
    ],
    "field_name2": [
      "may not be blank",
      "is not a valid email"
    ]
  }
}
Response Example (424 Failed Dependency)
{
  "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}

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

Authorization: string
in header

HMAC authorization using RP's SDK server credentials

id: string
in path

The ID of the identity document to get

OK

403 Forbidden

Forbidden - likely failed authentication

404 Not Found

Not Found

500 Internal Server Error

Server Error

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "string",
  "hash": "string",
  "type": "string",
  "verification_status": "string"
}
Response Example (403 Forbidden)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (404 Not Found)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}

Save an identity document for a user

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

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.

Authorization: string
in header

HMAC authorization using RP's SDK server credentials

userIdentifier: string
in path

A user identifier for the user

201 Created

Returned when the document was successfully added

422 Unprocessable Entity

When the request is invalid

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "string",
  "hash": "string",
  "type": "string",
  "verification_status": "string"
}

trusonafication_response

Accept a Trusonafication

POST /api/v2/trusonafication_responses

The response to the Trusonafication that was issued

payloads: string[]

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
Authorization: string
in header

HMAC authorization using SDK client credentials

Request Content-Types: application/json
Request Example
{
  "payloads": [
    "string"
  ]
}
201 Created

Created

Response Content-Types: application/json

Reject a Trusonafication

DELETE /api/v2/trusonafication_responses/{id}
Authorization: string
in header

HMAC authorization using SDK client credentials

id: object
in path

The ID of the Trusonafication to be rejected

204 No Content

The Trusonafication was successfully rejected

422 Unprocessable Entity

Rejecting Trusonafication failed

Response Content-Types: application/json

trusonafication

Get Trusonafication history for a user

GET /api/v2/trusonafications
Authorization: string
in header

HMAC'd request string

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "string",
    "status": "string",
    "user_identifier": "string",
    "device_identifier": "string",
    "trusona_id": "string",
    "desired_level": "integer",
    "expires_at": "string (date-time)",
    "created_at": "string (date-time)",
    "updated_at": "string (date-time)",
    "action": "string",
    "resource": "string",
    "relying_party": "string",
    "result": {
      "id": "string",
      "is_accepted": "boolean",
      "accepted_level": "integer",
      "device_identifier": "string",
      "user_identifier": "string"
    },
    "user_presence": "boolean",
    "prompt": "boolean",
    "show_identity_document": "boolean"
  }
]

Create a new trusonafication

POST /api/v2/trusonafications

The Trusonafication object that needs to be created

email: string

The email for the user, previously registered

trusona_id: string

The Trusona ID of the user

device_identifier: string

The identifier of the device registered with Trusona

user_identifier: string

The user identifier that was bound to at least one device in Trusona

action: string

The Trusonafication action

resource: string

The Trusonafication resource

desired_level: integer 1 ≤ x ≤ 3

The desired level for the Trusonafication (1=EN, 2=ES, 3=EX)

expires_at: string (date-time)

The timestamp when the Trusonafication expires

user_presence: boolean true

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)

prompt: boolean true

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

show_identity_document: boolean false

Whether or not to request the user to scan a registered identity document

Authorization: string
in header

HMAC'd request string

Request Content-Types: application/json
Request Example
{
  "email": "string",
  "trusona_id": "string",
  "device_identifier": "string",
  "user_identifier": "string",
  "action": "string",
  "resource": "string",
  "desired_level": "integer",
  "expires_at": "string (date-time)",
  "user_presence": "boolean",
  "prompt": "boolean",
  "show_identity_document": "boolean"
}
201 Created

Created

400 Bad Request

Bad Request

403 Forbidden

Forbidden - likely failed authentication

422 Unprocessable Entity

Unprocessable Entity

type
object
500 Internal Server Error

Server Error

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "string",
  "status": "string",
  "user_identifier": "string",
  "device_identifier": "string",
  "trusona_id": "string",
  "desired_level": "integer",
  "expires_at": "string (date-time)",
  "created_at": "string (date-time)",
  "updated_at": "string (date-time)",
  "action": "string",
  "resource": "string",
  "relying_party": "string",
  "result": {
    "id": "string",
    "is_accepted": "boolean",
    "accepted_level": "integer",
    "device_identifier": "string",
    "user_identifier": "string"
  },
  "user_presence": "boolean",
  "prompt": "boolean",
  "show_identity_document": "boolean"
}
Response Example (400 Bad Request)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (403 Forbidden)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}
Response Example (422 Unprocessable Entity)
{
  "message": "string",
  "errors": [
    "string"
  ]
}

Get next Trusonafication to handle

GET /api/v2/trusonafications/next
Authorization: string
in header

HMAC'd request string

OK

204 No Content

No pending Trusonafications

403 Forbidden

Forbidden - likely failed authentication

500 Internal Server Error

Server Error

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "string",
  "status": "string",
  "user_identifier": "string",
  "device_identifier": "string",
  "trusona_id": "string",
  "desired_level": "integer",
  "expires_at": "string (date-time)",
  "created_at": "string (date-time)",
  "updated_at": "string (date-time)",
  "action": "string",
  "resource": "string",
  "relying_party": "string",
  "result": {
    "id": "string",
    "is_accepted": "boolean",
    "accepted_level": "integer",
    "device_identifier": "string",
    "user_identifier": "string"
  },
  "user_presence": "boolean",
  "prompt": "boolean",
  "show_identity_document": "boolean"
}
Response Example (403 Forbidden)
{
  "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}
Authorization: string
in header

HMAC'd request string

id: string
in path

The record ID of the Trusonafication

OK

403 Forbidden

Forbidden - likely failed authentication

404 Not Found

Not Found - the record does not exist

500 Internal Server Error

Server Error

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "string",
  "status": "string",
  "user_identifier": "string",
  "device_identifier": "string",
  "trusona_id": "string",
  "desired_level": "integer",
  "expires_at": "string (date-time)",
  "created_at": "string (date-time)",
  "updated_at": "string (date-time)",
  "action": "string",
  "resource": "string",
  "relying_party": "string",
  "result": {
    "id": "string",
    "is_accepted": "boolean",
    "accepted_level": "integer",
    "device_identifier": "string",
    "user_identifier": "string"
  },
  "user_presence": "boolean",
  "prompt": "boolean",
  "show_identity_document": "boolean"
}
Response Example (403 Forbidden)
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed"
}

user

Deletes a user

DELETE /api/v2/users/{userIdentifier}

Deactivates all of the user's devices

Authorization: string
in header

HMAC authorization using RP's SDK server credentials

userIdentifier: string
in path

The userIdentifier known to the RP to be deleted

204 No Content

The delete was successful

403 Forbidden

RP's credentials were invalid

404 Not Found

The user was not found

500 Internal Server Error

An internal error occurred

user_identifier

Create a new user identifier entry

POST /api/v2/user_identifiers

undefined

Authorization: string
in header

HMAC authorization using RP's SDK server credentials

Request Example
{
  "trusona_id": "string",
  "identifier": "string"
}
204 No Content

The user identifier was created

409 Conflict

The user already has a user identifier associated

422 Unprocessable Entity

Validation failed

424 Failed Dependency

The user wasn't found

Look up a user identifier

GET /api/v2/user_identifiers/{identifier}
Authorization: string
in header

HMAC authorization using RP's SDK server credentials

identifier: object
in path

The identifier that was previously associated with the user

Succesfully found the Trusona user

Response Example (200 OK)
{
  "trusona_id": "string",
  "identifier": "string"
}

verification

Look up a Trusonafication (legacy endpoint)

GET /api/v1/verifications/{trusonaficationId}
Authorization: string
in header

HMAC authorization using user's credentials

trusonaficationId: object
in path

An ID of a Trusonafication

200 OK

Succesfully found the Trusonafication

Response Example (200 OK)
{
  "trusona_id": "string",
  "email": "string",
  "action": "string",
  "resource": "string",
  "agent_id": "string",
  "desired_level": "integer",
  "accepted_level": "integer",
  "callback_url": "string",
  "verification_id": "string",
  "display_name": "string",
  "status": "string",
  "interval": "integer",
  "relying_party_display_name": "string",
  "result_id": "string",
  "created_date": "integer",
  "updated_date": "integer"
}

Create a Trusonafication (legacy endpoint)

POST /api/v1/verifications

undefined

Authorization: string
in header

HMAC authorization using user's credentials

Request Example
{
  "id": "string",
  "status": "string",
  "user_identifier": "string",
  "device_identifier": "string",
  "trusona_id": "string",
  "desired_level": "integer",
  "expires_at": "string (date-time)",
  "created_at": "string (date-time)",
  "updated_at": "string (date-time)",
  "action": "string",
  "resource": "string",
  "relying_party": "string",
  "result": {
    "id": "string",
    "is_accepted": "boolean",
    "accepted_level": "integer",
    "device_identifier": "string",
    "user_identifier": "string"
  },
  "user_presence": "boolean",
  "prompt": "boolean",
  "show_identity_document": "boolean"
}
201 Created

Successfully created the Trusonafication

Schema Definitions

UserDevice: object

device_identifier: string
user_identifier: string
Example
{
  "device_identifier": "string",
  "user_identifier": "string"
}

UserDeviceResponse: object

id: string

The id of the device+user binding that can be use to later activate it.

active: boolean false

Indicates if the device+user binding is active.

activated_at: string

Timestamp when the device+user binding was activated

Example
{
  "device_identifier": "string",
  "user_identifier": "string",
  "id": "string",
  "active": "boolean",
  "activated_at": "string"
}

Device: object

device_public_key: JsonWebKey
auth_public_key: JsonWebKey
device_platform: string android, ios
bundle_id: string
Example
{
  "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"
}

DeviceResponse: object

is_active: boolean

Whether or not the device has been activated

activated_at: string (date-time)

The timestamp when the device was activated

Example
{
  "is_active": "boolean",
  "activated_at": "string (date-time)"
}

IdentityDocument: object

id: string
hash: string
type: string AAMVA_DRIVERS_LICENSE AAMVA_DRIVERS_LICENSE
verification_status: string UNVERIFIED, UNVERIFIABLE, VERIFIED, FAILED
Example
{
  "id": "string",
  "hash": "string",
  "type": "string",
  "verification_status": "string"
}

AAMVADriversLicense: object

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

Trusonafication: object

id: string

The record ID for the Trusonafication

status: string INVALID, IN_PROGRESS, REJECTED, ACCEPTED, ACCEPTED_AT_LOWER_LEVEL, ACCEPTED_AT_HIGHER_LEVEL, EXPIRED

The status of the Trusonafication

user_identifier: string

The identifier of the user that has been issued a Trusonafication

device_identifier: string

The device identifier that was used, if any, to determine the user identifier of the Trusonafication

trusona_id: string

The public Trusona ID of the user being Trusonafied

desired_level: integer 1 ≤ x ≤ 3

The desired level for the Trusonafication (1=EN, 2=ES, 3=EX)

expires_at: string (date-time)

The timestamp when the Trusonafication expires

created_at: string (date-time)

The timestamp when the Trusonafication was created

updated_at: string (date-time)

The timestamp when the Trusonafication last updated

action: string

The Trusonafication action

resource: string

The Trusonafication resource

relying_party: string

The display name for the Relying Party

result: TrusonaficationResult
user_presence: boolean

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)

prompt: boolean

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

show_identity_document: boolean

Whether or not to request the user to scan a registered identity document

Example
{
  "id": "string",
  "status": "string",
  "user_identifier": "string",
  "device_identifier": "string",
  "trusona_id": "string",
  "desired_level": "integer",
  "expires_at": "string (date-time)",
  "created_at": "string (date-time)",
  "updated_at": "string (date-time)",
  "action": "string",
  "resource": "string",
  "relying_party": "string",
  "result": {
    "id": "string",
    "is_accepted": "boolean",
    "accepted_level": "integer",
    "device_identifier": "string",
    "user_identifier": "string"
  },
  "user_presence": "boolean",
  "prompt": "boolean",
  "show_identity_document": "boolean"
}

TrusonaficationArray: array

Example
[
  {
    "id": "string",
    "status": "string",
    "user_identifier": "string",
    "device_identifier": "string",
    "trusona_id": "string",
    "desired_level": "integer",
    "expires_at": "string (date-time)",
    "created_at": "string (date-time)",
    "updated_at": "string (date-time)",
    "action": "string",
    "resource": "string",
    "relying_party": "string",
    "result": {
      "id": "string",
      "is_accepted": "boolean",
      "accepted_level": "integer",
      "device_identifier": "string",
      "user_identifier": "string"
    },
    "user_presence": "boolean",
    "prompt": "boolean",
    "show_identity_document": "boolean"
  }
]

TrusonaficationResult: object

id: string

The record ID for the TrusonaficationResult

is_accepted: boolean

Indiciates if the Trusonfication was accepted

accepted_level: integer

The level for which the Trusonafication was accepted (1=EN, 2=ES, 3=EX)

device_identifier: string

The identifier of the device that responded to the Trusonafication

user_identifier: string

The user identifier bound to the device that responded to the Trusonafication

Example
{
  "id": "string",
  "is_accepted": "boolean",
  "accepted_level": "integer",
  "device_identifier": "string",
  "user_identifier": "string"
}

Error: object

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

ErrorWithFields:

field_errors: object
Example
{
  "error": "Error occurred",
  "message": "Could not perform requested action",
  "description": "The specific reason the action could not be performed",
  "field_errors": {
    "field_name1": [
      "may not be blank"
    ],
    "field_name2": [
      "may not be blank",
      "is not a valid email"
    ]
  }
}

JsonWebKey: object

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

kty: string
alg: string
Example
{
  "kty": "RSA",
  "e": "AQAB",
  "n": "v7YNzZE1T0kfKklrmWPfslGdrD3ftqQZV0yPqhUHPkeH9Bww30S6mWzGFRQLaRppcJzy1InOoD-w7FgMSggoEvvW0daMoXFWPtiGSXrCDIih58kBU_Cu0SOtHMFxbNwoPgTuMqq-TB9xnhUh3ZwJhxdEEJaNhGyO6AP5Cn3BetGEMUA_tnMNnOP3BBc28qRVzzk0mgnI7icrZyacJ7LHaZZ1D6h9A5A8YxPoC3QUYu-vTXInPR5tCRiSt2HB8IOnk10xuLPengI7wxruLwmVA4BnC1cS5nDpVoIiWE9yO6LUn0fmhGpRWBLU36q1JMoLjegK34v-hsIxLq75KUJ0dw",
  "alg": "RS256"
}

TrusonaficationResponsePayload: object

The base information that all Trusonafication responds payloads share

type: string device_ar, user_presence, aamva_drivers_license

The type of response payload this is

trusonafication_id: string

The ID of the Trusonafication this is in response to

Example
{
  "type": "string",
  "trusonafication_id": "string"
}

DeviceArPayload:

Anti-replay and device verification payload signed by the device key. The type field should be device_ar.

type: string device_ar
device_identifier: string

The Trusona identifier for the device

nonce: string

A nonce generated on the device prior to sending the payload

checksum: string

A checksum of the nonce and device identifier formatted as sha256Hex(nonce:device_identifier)

accelerometer: number[]

A set of three numbers representing the acceleration of the device in three dimensional space

number
gyro: number[]

A set of three numbers representing the rotation of the device around it's three primary axes

number
Example
{
  "type": "string",
  "device_identifier": "string",
  "nonce": "string",
  "checksum": "string",
  "accelerometer": [
    "number"
  ],
  "gyro": [
    "number"
  ],
  "trusonafication_id": "string"
}

UserPresencePayload:

User presence payload signed by the auth key. The type field should be user_presence.

type: string user_presence
device_identifier: string

The Trusona identifier for the device

Example
{
  "type": "string",
  "device_identifier": "string",
  "trusonafication_id": "string"
}

AAMVALicensePayload:

Driver's license payload signed by the device key. The type field should be aamva_drivers_license.

type: string aamva_drivers_license
device_identifier: string

The Trusona identifier for the device

hash: string

The device generated hash of the scanned data from a user's driver's license

nonce: string

Nonce generated at the time of the scan

scan_x: number

X position of box within the camera viewport where the barcode was located

scan_y: number

Y position of box within the camera viewport where the barcode was located

scan_width: number

Width of box within the camera viewport where the barcode was located

scan_height: number

Height of box within the camera viewport where the barcode was located

scan_time: number

Time in seconds to scan the document

Example
{
  "type": "string",
  "device_identifier": "string",
  "hash": "string",
  "nonce": "string",
  "scan_x": "number",
  "scan_y": "number",
  "scan_width": "number",
  "scan_height": "number",
  "scan_time": "number",
  "trusonafication_id": "string"
}

UserIdentifier: object

trusona_id: string
identifier: string
Example
{
  "trusona_id": "string",
  "identifier": "string"
}

Verification: object

trusona_id: string
email: string
action: string
resource: string
agent_id: string
desired_level: integer
accepted_level: integer
callback_url: string
verification_id: string
display_name: string
status: string
interval: integer
relying_party_display_name: string
result_id: string
created_date: integer
updated_date: integer
Example
{
  "trusona_id": "string",
  "email": "string",
  "action": "string",
  "resource": "string",
  "agent_id": "string",
  "desired_level": "integer",
  "accepted_level": "integer",
  "callback_url": "string",
  "verification_id": "string",
  "display_name": "string",
  "status": "string",
  "interval": "integer",
  "relying_party_display_name": "string",
  "result_id": "string",
  "created_date": "integer",
  "updated_date": "integer"
}