1. FIDO registration and authentication

1. FIDO registration and authentication

1.1. Overview

Trusona’s APIs for registering and authenticating users using webauthn

1.1.1. Version information

Version : 1.5.1

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. If you know for which reqistered user the authentication is being created, that hint of a user identifier can be provided. 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	request optional	createAuthenticationRequest

createAuthenticationRequest

Name	Description	Schema
callback_url optional	A `HTTPS` 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
user_identifier optional	Hint of the `user_identifier` to create the authentication for. This is only used if an encrypted cookie value of the user identifier is not available.	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
422	If a user identifier was provided, and the user does not exist or the user exists, but has not yet registered.	No Content
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 an Organization

POST /api/v1/organizations

1.2.3.1. Parameters

Type	Name	Schema
Body	request optional	createOrganizationRequest

createOrganizationRequest

Name	Description	Schema
domain_name required	The domain to be used for user link generation	string
name required	A display name for the Organization. Will be displayed during FIDO flows.	string
require_platform_authenticator optional	Require the user to use a platform authentication (Touch ID, Face ID, Biometrics, etc..), not a roaming authenticator. Defaults to false (any authenticator is allowed).	boolean
require_resident_key optional	Controls the residentKey authenticator selection parameter. When to true will set residentKey to ‘required’ in the create options. Otherwise, it will be set to ‘preferred’. Defaults to false.	boolean
verify_attestation_statement optional	Whether or not to verify the attestation statement of the authenticator during FIDO registration. Defaults to true (does verify the attestation statement).	boolean

1.2.3.2. Responses

HTTP Code	Description	Schema
201	Successfully created the Organization	Organization
500	An unexpected error has occurred.	No Content

1.2.3.3. Consumes

application/json

1.2.3.4. Produces

application/json

1.2.3.5. Tags

mobile auth

1.2.4. Get an Organization

GET /api/v1/organizations/{id}

1.2.4.1. Parameters

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

1.2.4.2. Responses

HTTP Code	Description	Schema
201	Successfully retrieved the Organization	Organization
404	The Organization referenced by the id does not exist	No Content
500	An unexpected error has occurred	No Content

1.2.4.3. Produces

application/json

1.2.4.4. Tags

mobile auth

1.2.5. Create an organization’s redirect URI

POST /api/v1/redirect_uris

1.2.5.1. Parameters

Type	Name	Schema
Body	request optional	createRedirectUriRequest

createRedirectUriRequest

Name	Description	Schema
uri optional	The valid URI to be created e.g. https://foo.bar.com/callback	string

1.2.5.2. Responses

HTTP Code	Description	Schema
201	Successfully created the redirect URI	RedirectUri
400	A client request error occurred	No Content
404	The Organization referenced by the id does not exist	No Content
500	An unexpected error has occurred	No Content

1.2.5.3. Produces

application/json

1.2.5.4. Tags

mobile auth

1.2.6. Get a list of an organization’s redirect URIs

GET /api/v1/redirect_uris

1.2.6.1. Responses

HTTP Code	Description	Schema
200	Successfully returns the list of redirect URIs	< RedirectUri > array
404	The Organization referenced by the id does not exist	No Content
500	An unexpected error has occurred	No Content

1.2.6.2. Produces

application/json

1.2.6.3. Tags

mobile auth

1.2.7. Create a Registration with User

POST /api/v1/registrations

1.2.7.1. Description

Create a Registration, for a given user, 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.

If the user does not already exist, it will be created. This provides a simplified way to do user registrations in one api call.

1.2.7.2. Parameters

Type	Name	Schema
Body	request optional	createRegistrationWithUserBody

createRegistrationWithUserBody

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
user required		user

user

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

1.2.7.3. Responses

HTTP Code	Description	Schema
201	Successfully created a link that can be sent to a consumer to start registration	createRegistrationResponse
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

createRegistrationResponse

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 48 hours (e.g. https://login.acme.com/credentials?registration_id=beb9467a-2788-4a55-ad24-e366abed6eca&secret=c6Ba67riEprG3J4VFjzFBP9Y)	string

1.2.7.4. Consumes

application/json

1.2.7.5. Produces

application/json

1.2.7.6. Tags

mobile auth

1.2.8. Create a User

POST /api/v1/users

1.2.8.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.8.2. Parameters

Type	Name	Schema
Body	request optional	createUserRequest

createUserRequest

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.8.3. Responses

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

1.2.8.4. Consumes

application/json

1.2.8.5. Produces

application/json

1.2.8.6. Tags

mobile auth

1.2.9. Search Users

POST /api/v1/users/search

1.2.9.1. Description

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

1.2.9.2. Parameters

Type	Name	Schema
Body	search optional	UserSearch

UserSearch

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.9.3. Responses

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

userSearchResponse

Name	Schema
users optional	< User > array

1.2.9.4. Consumes

application/json

1.2.9.5. Produces

application/json

1.2.9.6. Tags

mobile auth

1.2.10. Create a Registration for a user

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

1.2.10.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.10.2. Parameters

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

createRegistrationRequest

Name	Description	Schema
callback_url optional	URL to receive status updates for the registration	string
redirect_url optional	A HTTPS URL to display or link the user to upon successful registration	string
sms_phone_number optional	A phone number to send the user link to via SMS	string

1.2.10.3. Responses

HTTP Code	Description	Schema
201	Successfully created a link that can be sent to a consumer to start registration	createRegistrationResponse
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