Skip to main content
API docs by Redocly

FIDO2 API (2.0)

RESTful API for handling WebAuthn logic with support for FIDO2 flows with passkeys.

mgmt

Management API

Create an authorization token with requested scopes

Authorizations:
apiKey_header_Authorization
Request Body schema: application/json
required
grants
required
Array of strings
Items Enum: "passkey:read" "passkey:write" "profile:read" "profile:write" "reg:write" "auth:write"

List of requested grants

username
string

User identifier

Responses

Request samples

Content type
application/json
{
  • "grants": [
    ],
  • "username": "testUser"
}

Response samples

Content type
application/json
{
  • "token": "oWIsYWQl6RB0cFC9jM8Hy85TmqAMyc0QqSXMsh0Fo9U="
}

Validate JWT Access Token

Authorizations:
apiKey_header_Authorization
Request Body schema: application/json
required
jwtAccess
required
string

JWT access token

Responses

Request samples

Content type
application/json
{
  • "jwtAccess": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response samples

Content type
application/json
{
  • "msg": "A serious error",
  • "msgCode": "serious_error"
}

passkeys

FIDO2 pass-key management

List passkeys

Authorizations:
jwt_header_Authorization

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Delete passkey

Authorizations:
jwt_header_Authorization
path Parameters
id
required
string
Example: 2a363a42-a397-4af0-b089-0935fc223017

Internal passkey identifier

Responses

Response samples

Content type
application/json
{
  • "msg": "A serious error",
  • "msgCode": "serious_error"
}

Rename passkey

Authorizations:
jwt_header_Authorization
path Parameters
id
required
string
Example: 2a363a42-a397-4af0-b089-0935fc223017

Internal passkey identifier

Request Body schema: application/json
required
name
required
string

Internal passkey identifier

Responses

Request samples

Content type
application/json
{
  • "name": "My iPhone SE"
}

Response samples

Content type
application/json
{
  • "msg": "A serious error",
  • "msgCode": "serious_error"
}

profile

User Profile API

Delete a user profile and all associated passkey

Authorizations:
apiKey_header_Authorization
path Parameters
id
required
string
Example: 2a363a42-a397-4af0-b089-0935fc223017

Internal user identifier

Responses

Response samples

Content type
application/json
{
  • "msg": "A serious error",
  • "msgCode": "serious_error"
}

Update profile email address

Authorizations:
apiKey_header_Authorization
path Parameters
id
required
string
Example: 2a363a42-a397-4af0-b089-0935fc223017

Internal user identifier

Request Body schema: application/json
required
email
required
string

Email address

requestVerification
boolean
Default: true

Whether to update the email address immediately or send an authorization code to verify.

Responses

Request samples

Content type
application/json
{
  • "email": "luke.skywalker@tatuin.com",
  • "requestVerification": true
}

Response samples

Content type
application/json
{
  • "msg": "A serious error",
  • "msgCode": "serious_error"
}

Delete phone from the profile

Authorizations:
apiKey_header_Authorization
path Parameters
id
required
string
Example: 2a363a42-a397-4af0-b089-0935fc223017

Internal user identifier

Responses

Response samples

Content type
application/json
{
  • "msg": "A serious error",
  • "msgCode": "serious_error"
}

Update the profile phone number

Authorizations:
apiKey_header_Authorization
path Parameters
id
required
string
Example: 2a363a42-a397-4af0-b089-0935fc223017

Internal user identifier

Request Body schema: application/json
required
messagingConsent
boolean
Default: false

Whether the user consents to receiving SMS messages on this number. The phone will not be used for sending messages if no consent is provided.

phoneNumber
required
string

Phone number

requestVerification
boolean
Default: true

Whether to update the phone number immediately or send an authorization code to verify. This method will fail if verification is requested but no consent is provided.

Responses

Request samples

Content type
application/json
{
  • "messagingConsent": true,
  • "phoneNumber": "+14161234567",
  • "requestVerification": true
}

Response samples

Content type
application/json
{
  • "msg": "A serious error",
  • "msgCode": "serious_error"
}

Verify phone number with received authorization code

Request Body schema: application/json
required
authCode
required
string

Verification code

username
required
string

Username associated with the code

Responses

Request samples

Content type
application/json
{
  • "authCode": "123456",
  • "username": "user@example.com"
}

Response samples

Content type
application/json
{
  • "msg": "A serious error",
  • "msgCode": "serious_error"
}

Verify phone number with received authorization code

Request Body schema: application/json
required
authCode
required
string

Verification code

username
required
string

Username associated with the code

Responses

Request samples

Content type
application/json
{
  • "authCode": "123456",
  • "username": "user@example.com"
}

Response samples

Content type
application/json
{
  • "msg": "A serious error",
  • "msgCode": "serious_error"
}

auth

FIDO2 authentication flow

Complete WebAuthn registration

Request Body schema: application/json
required
required
object (AuthenticatorAssertionResponse)
session
required
string >= 16 characters

An opaque object containing session data.

Responses

Request samples

Content type
application/json
{
  • "assertionResult": {
    },
  • "session": "w5zY9tpNgePsqkTsQlNPVCR2rwUlCdhCLhVwXsN2r..."
}

Response samples

Content type
application/json
{
  • "deviceID": "2a363a42-a397-4af0-b089-0935fc223017",
  • "jwtAccess": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Start WebAuthn registration flow

header Parameters
User-Agent
string
Example: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36

Raw user-agent header as set by a browser

Request Body schema: application/json
required
required
object (Application)

Application making the request. It contains additional info about the caller to distinguish between tenants.

required
object (DeviceInfo)

Information about the device. All of these attributes are optional and should be provided on best effort basis. If provide, they will be taken into consideration in order to improve user experience.

object (UserLogin)

Responses

Request samples

Content type
application/json
{
  • "app": {
    },
  • "deviceInfo": {
    },
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "action": "proceed",
  • "assertionOptions": {
    },
  • "crossAuthMethods": [
    ],
  • "fallbackMethods": [
    ],
  • "passkeyType": "device",
  • "session": "w5zY9tpNgePsqkTsQlNPVCR2rwUlCdhCLhVwXsN2r..."
}

Request OTP code by an authenticated user

An authenticated user can request an authentication code directly using this method. The code can be used for authentication from another device.

Authorizations:
jwt_header_Authorization

Responses

Response samples

Content type
application/json
{
  • "code": "123456",
  • "expiresAt": "2021-01-01T00:00:00Z"
}

Request OTP code to be sent via email.

Send authentication code to the provided email. The SMS will only be sent if the email address is known to the application, however, this method will return success regardless.

Request Body schema: application/json
required
required
object (UserLogin)
username
required
string

Username

usernameType
required
string
Default: "email"
Enum: "email" "phone"

Username type

Responses

Request samples

Content type
application/json
{
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "msg": "A serious error",
  • "msgCode": "serious_error"
}

Request OTP code to be sent via SMS.

Send authentication code to the provided phone number. The SMS will only be sent if the phone is registered with the application, however, it will return success regardless.

Request Body schema: application/json
required
required
object (UserLogin)
username
required
string

Username

usernameType
required
string
Default: "email"
Enum: "email" "phone"

Username type

Responses

Request samples

Content type
application/json
{
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "msg": "A serious error",
  • "msgCode": "serious_error"
}

Verify authentication code and return JWT access token with appropriate scopes

Request Body schema: application/json
required
authCode
required
string

Authentication code

required
object (UserLogin)

Responses

Request samples

Content type
application/json
{
  • "authCode": "123456",
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "deviceID": "2a363a42-a397-4af0-b089-0935fc223017",
  • "jwtAccess": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

reg

FIDO2 registration flow

Complete WebAuthn registration flow

Request Body schema: application/json
required
required
object (CreationResult)
session
required
string >= 16 characters

An opaque object containing session data.

Responses

Request samples

Content type
application/json
{
  • "creationResult": {
    },
  • "session": "w5zY9tpNgePsqkTsQlNPVCR2rwUlCdhCLhVwXsN2r..."
}

Response samples

Content type
application/json
{
  • "deviceID": "2a363a42-a397-4af0-b089-0935fc223017",
  • "jwtAccess": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Start WebAuthn registration flow

Authorizations:
jwt_header_Authorization
header Parameters
User-Agent
string
Example: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36

Raw user-agent header as set by a browser

Request Body schema: application/json
required
required
object (Application)

Application making the request. It contains additional info about the caller to distinguish between tenants.

required
object (DeviceInfo)

Information about the device. All of these attributes are optional and should be provided on best effort basis. If provide, they will be taken into consideration in order to improve user experience.

object (PasskeyOptions)
session
string >= 16 characters

An opaque object containing user data. It is used in place of "user" attribute for creating passkeys for pre-authorized users ("user" attribute is ignored if session is present). The value of this attribute is generated by this service and require backend integration for obtaining it. This value is time sensitive and has rather short expiry.

object (User)

Responses

Request samples

Content type
application/json
{
  • "app": {
    },
  • "deviceInfo": {
    },
  • "passkeyOptions": {
    },
  • "session": "w5zY9tpNgePsqkTsQlNPVCR2rwUlCdhCLhVwXsN2r...",
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "action": "proceed",
  • "registrationRequestOptions": {
    },
  • "session": "w5zY9tpNgePsqkTsQlNPVCR2rwUlCdhCLhVwXsN2r..."
}

tx

FIDO2 transaction confirmation flow

Complete transaction confirmation

Request Body schema: application/json
required
authenticatorData
required
string

This attribute contains the authenticator data returned by the authenticator.

clientData
required
string

Base64 encoded byte array which is a JSON-compatible serialization of client data passed to the authenticator by the client in order to generate this assertion. The exact JSON serialization MUST be preserved, as the hash of the serialized client data has been computed over it.

keyHandle
required
string

Identified of the passkey credential.

session
required
string >= 16 characters

An opaque object containing session data.

signature
required
string

Base64 encoded the raw signature returned from the authenticator.

Responses

Request samples

Content type
application/json
{
  • "authenticatorData": "ix523n3XniH01jM4CIuOn1z0Jw6QbRATXYOsCUyQN...",
  • "clientData": "UxaynsCYdykyHKaA0G7IeWaBG6DGJoGFN8mbJgvRo...",
  • "keyHandle": "UxaynsCYdykyHKaA0G7IeWaBG6DGJoGFN8mbJgvRo...",
  • "session": "w5zY9tpNgePsqkTsQlNPVCR2rwUlCdhCLhVwXsN2r...",
  • "signature": "UxaynsCYdykyHKaA0G7IeWaBG6DGJoGFN8mbJgvRo..."
}

Response samples

Content type
application/json
{
  • "authCred": {
    },
  • "credentialId": "2a363a42-a397-4af0-b089-0935fc223017",
  • "jwtAccess": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "lNonce": "w5zY9tpNgePsqkTsQlNPVCR2rwUlCdhCLhVwXsN2r...",
  • "nonce": "w5zY9tpNgePsqkTsQlNPVCR2rwUlCdhCLhVwXsN2r...",
  • "txHash": "w5zY9tpNgePsqkTsQlNPVCR2rwUlCdhCLhVwXsN2r...",
  • "txId": "2a363a42-a397-4af0-b089-0935fc223017"
}

Start transaction confirmation flow

Request Body schema: application/json
required
nonce
required
string

Random string

txPayload
required
string

Payload of transaction

txType
required
string

Type of transaction

username
required
string

Username of user

Responses

Request samples

Content type
application/json
{
  • "nonce": "w5zY9tpNgePsqkTsQlNPVCR2rwUlCdhCLhVwXsN2r...",
  • "txPayload": "UxaynsCYdykyHKaA0G7IeWaBG6DGJoGFN8mbJgvRo...",
  • "txType": "raw",
  • "username": "testUser"
}

Response samples

Content type
application/json
{
  • "assertionOptions": {
    },
  • "session": "w5zY9tpNgePsqkTsQlNPVCR2rwUlCdhCLhVwXsN2r...",
  • "txId": "2a363a42-a397-4af0-b089-0935fc223017"
}

.well-known

FIDO2 well-known endpoints

JWKS for auth token validation

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

version

Get Version

Show software version

Responses

Response samples

Content type
application/json
{
  • "hash": "cd243db4",
  • "version": "1.2.3"
}