Mobile Auth for Browsers Service

By Trusona Engineering
Updated Jun 2, 2021

• 1. FIDO registration and authentication
  • 1.1. Overview
    • 1.1.1. Version information
    • 1.1.2. URI scheme
  • 1.2. Paths
    • 1.2.1. Create an Authentication
      • 1.2.1.1. Description
      • 1.2.1.2. Parameters
      • 1.2.1.3. Responses
      • 1.2.1.4. Consumes
      • 1.2.1.5. Produces
      • 1.2.1.6. Tags
    • 1.2.2. Get an Authentication
      • 1.2.2.1. Description
      • 1.2.2.2. Parameters
      • 1.2.2.3. Responses
      • 1.2.2.4. Produces
      • 1.2.2.5. Tags
    • 1.2.3. Create a User
      • 1.2.3.1. Description
      • 1.2.3.2. Parameters
      • 1.2.3.3. Responses
      • 1.2.3.4. Consumes
      • 1.2.3.5. Produces
      • 1.2.3.6. Tags
    • 1.2.4. Search Users
      • 1.2.4.1. Description
      • 1.2.4.2. Parameters
      • 1.2.4.3. Responses
      • 1.2.4.4. Consumes
      • 1.2.4.5. Produces
      • 1.2.4.6. Tags
    • 1.2.5. Create a Registration
      • 1.2.5.1. Description
      • 1.2.5.2. Parameters
      • 1.2.5.3. Responses
      • 1.2.5.4. Consumes
      • 1.2.5.5. Produces
      • 1.2.5.6. Tags
  • 1.3. Definitions
    • 1.3.1. Authentication
    • 1.3.2. Registration
    • 1.3.3. User
  • 1.4. Security
    • 1.4.1. Token

1. FIDO registration and authentication

1.1. Overview

Trusona’s APIs for registering and authenticating users using webauthn

1.1.1. Version information

Version : 0.9.0

1.1.2. URI scheme

Host : sirius.trusona.net BasePath : / Schemes : HTTPS

1.2. Paths

1.2.1. Create an Authentication

POST /api/v1/authentications

1.2.1.1. Description

Create an authentication to be completed by a registered user. This returns a link that your user must click on to perform the authentication. You can optionally provide a callback URL that will be notified of updates to the Authentication or a phone number that we will deliver the Authentication link to via SMS.

1.2.1.2. Parameters

Type	Name	Schema
Body	body optional	body

body

Name	Description	Schema
callback_url optional	URL to receive status updates for the authentication attempt	string
sms_phone_number optional	A phone number to send the user authentication link to via SMS	string

1.2.1.3. Responses

HTTP Code	Description	Schema
201	Successfully created A link that can be sent to a consumer to start login	Authentication
500	An unexpected error has occurred	No Content

1.2.1.4. Consumes

• application/json

1.2.1.5. Produces

• application/json

1.2.1.6. Tags

• mobile auth

1.2.2. Get an Authentication

GET /api/v1/authentications/{id}

1.2.2.1. Description

Use this endpoint to get the status of an Authentication you created.

1.2.2.2. Parameters

Type	Name	Description	Schema
Path	id required	The ID of an authentication	string

1.2.2.3. Responses

HTTP Code	Description	Schema
200	Successfully retrieved the authentication	Authentication
404	The authentication could not be found	No Content
500	An unexpected error has occurred	No Content

1.2.2.4. Produces

• application/json

1.2.2.5. Tags

• mobile auth

1.2.3. Create a User

POST /api/v1/users

1.2.3.1. Description

Use this API to create a new user in your system. Users need to be registered by creating a Registration for them. Once registered, they can then accept Authentications.

1.2.3.2. Parameters

Type	Name	Schema
Body	body optional	body

body

Name	Description	Schema
name required	A human friendly display name for the registering user	string
user_identifier required	An identifier that uniquely identifies this user in your system	string

1.2.3.3. Responses

HTTP Code	Description	Schema
201	The created user	User
400	The request body is missing required fields	No Content

1.2.3.4. Consumes

• application/json

1.2.3.5. Produces

• application/json

1.2.3.6. Tags

• mobile auth

1.2.4. Search Users

GET /api/v1/users/search

1.2.4.1. Description

Use this endpoint to lookup users. You can search by the user_identifier and their registration status.

1.2.4.2. Parameters

Type	Name	Schema
Body	body optional	body

body

Name	Description	Schema
registered optional	Set to true to return only registered users, or to false for users who have not yet completed registration	boolean
user_identifier optional	The user identifier to search for	string

1.2.4.3. Responses

HTTP Code	Description	Schema
200	The users search results	Response 200
500	An unexpected error has occurred	No Content

Response 200

Name	Schema
users optional	< User > array

1.2.4.4. Consumes

• application/json

1.2.4.5. Produces

• application/json

1.2.4.6. Tags

• mobile auth

1.2.5. Create a Registration

POST /api/v1/users/{user_id}/registrations

1.2.5.1. Description

Create a Registration that can be used to enroll, or re-enroll a user’s mobile device. Registrations are created for specific users in your system. You can optionally provide a callback URL that will be notified of updates to the Registration or a phone number that we will deliver the user link to via SMS.

1.2.5.2. Parameters

Type	Name	Description	Schema
Path	user_id required	The id of a previously created and registered user	string
Body	body optional		body

body

Name	Description	Schema
callback_url optional	URL to receive status updates for the registration	string
sms_phone_number optional	A phone number to send the user link to via SMS	string

1.2.5.3. Responses

HTTP Code	Description	Schema
201	Successfully created a link that can be sent to a consumer to start registration	Response 201
400	The request body is missing required fields	No Content
404	No user is found for the provided user_id	No Content
500	Unexpected error	No Content

Response 201

Name	Description	Schema
id optional	The ID for the registration that was created	string
user_link optional	A link that can be sent to a consumer to start registration. This link will expire in 10 minutes (e.g. https://login.acme.com/credentials?registration_id=beb9467a-2788-4a55-ad24-e366abed6eca&secret=c6Ba67riEprG3J4VFjzFBP9Y)	string

1.2.5.4. Consumes

• application/json

1.2.5.5. Produces

• application/json

1.2.5.6. Tags

• mobile auth

1.3. Definitions

1.3.1. Authentication

Name	Description	Schema
callback_url optional	URL to receive status updates for the authentication attempt	string
id optional	The ID for the authentication that was created. You can use this to retrieve the status of the Authentication.	string
sms_phone_number optional	A phone number to send the user authentication link to via SMS	string
status optional	The status of the authentication. * PENDING - The user has not yet performed the authentication * COMPLETED - The user completed the authentication successfully * EXPIRED - The user did not complete the authentication in a timely manner. * ERROR - An error occurred while processing the authentication.	enum (PENDING, ACCEPTED, EXPIRED, ERROR)
user optional		User
user_link optional	A link to the login page that the user must navigate to to complete the authentication.	string

1.3.2. Registration

Name	Description	Schema
callback_url optional	URL to receive status updates for the authentication attempt	string
id optional	The ID for the registration that was created	string
sms_phone_number optional	A phone number to send the user authentication link to via SMS	string
user optional		User
user_link optional	A link that can be sent to a consumer to start registration. This link will expire in 10 minutes (e.g. https://login.acme.com/credentials?registration_id=beb9467a-2788-4a55-ad24-e366abed6eca&secret=c6Ba67riEprG3J4VFjzFBP9Y)	string

1.3.3. User

Name	Description	Schema
id optional	A system-generated unique identifier for the user	string
name optional	The provided human friendly display name for the registering user	string
registered optional	Set to true if the user has gone through registration at least once	boolean
user_identifier optional	The provided identifier that uniquely identifies this user in your system	string

1.4. Security

1.4.1. Token

Your API token will be provided by Trusona during onboarding. The Authorization header should use a type of TRUSONA. For example Authorization: TRUSONA <token>

Type : apiKey Name : Authorization In : HEADER

---