Trusona Service

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

1. What’s in this doc

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. Save an identity document for a user

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

4.25.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.25.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.25.3. Responses

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

4.25.4. Consumes

  • application/json

4.25.5. Produces

  • application/json

4.26. Get keys used to sign device identifier JWTs

GET /jwks

4.26.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. 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.4. 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.5. 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.6. Error

Name Schema
description
required
string
error
required
string
message
required
string

5.7. ErrorWithFields

Polymorphism : Composition

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

5.8. 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.9. JsonWebKey

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

Name Schema
alg
required
string
kty
required
string

5.10. 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.11. 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.12. 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.13. 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.14. UserDevice

Name Schema
device_identifier
required
string
user_identifier
required
string

5.15. 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.16. UserIdentifier

Name Schema
identifier
required
string
trusona_id
required
string

5.17. 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.18. 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

Guides
Mobile SDKs
Server SDKs
Web SDKs
SSO and IAM
VPN
PAM
RADIUS
Productivity
REST API
Users Guides
Implementation Guides