FusionAuth Two Factor API
The Two Factor API from FusionAuth — 7 operation(s) for two factor.
OpenAPI Specification
openapi: 3.0.3
info:
version: 1.66.0
title: FusionAuth Api Key Two Factor API
description: This is a FusionAuth server. Find out more at [https://fusionauth.io](https://fusionauth.io). You need to [set up an API key](https://fusionauth.io/docs/v1/tech/apis/authentication#managing-api-keys) in the FusionAuth instance you are using to test out the API calls.
license:
name: Apache2
servers:
- url: http://localhost:9011
- url: https://sandbox.fusionauth.io
security:
- ApiKeyAuth: []
tags:
- name: Two Factor
paths:
/api/two-factor/login:
post:
description: Complete login using a 2FA challenge
operationId: twoFactorLoginWithId
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFactorLoginRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/LoginResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
tags:
- Two Factor
/api/two-factor/secret:
get:
description: Generate a Two Factor secret that can be used to enable Two Factor authentication for a User. The response will contain both the secret and a Base32 encoded form of the secret which can be shown to a User when using a 2 Step Authentication application such as Google Authenticator.
operationId: generateTwoFactorSecretUsingJWTWithId
security:
- BearerAuth: []
parameters: []
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SecretResponse'
default:
description: Error
tags:
- Two Factor
/api/two-factor/send:
post:
description: Send a Two Factor authentication code to assist in setting up Two Factor authentication or disabling.
operationId: sendTwoFactorCodeForEnableDisableWithId
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFactorSendRequest'
responses:
'200':
description: Success
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
tags:
- Two Factor
/api/two-factor/send/{twoFactorId}:
post:
description: Send a Two Factor authentication code to allow the completion of Two Factor authentication.
operationId: sendTwoFactorCodeForLoginUsingMethodWithId
parameters:
- name: twoFactorId
in: path
schema:
type: string
required: true
description: The Id returned by the Login API necessary to complete Two Factor authentication.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFactorSendRequest'
responses:
'200':
description: Success
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
tags:
- Two Factor
/api/two-factor/start:
post:
description: Start a Two-Factor login request by generating a two-factor identifier. This code can then be sent to the Two Factor Send API (/api/two-factor/send)in order to send a one-time use code to a user. You can also use one-time use code returned to send the code out-of-band. The Two-Factor login is completed by making a request to the Two-Factor Login API (/api/two-factor/login). with the two-factor identifier and the one-time use code. This API is intended to allow you to begin a Two-Factor login outside a normal login that originated from the Login API (/api/login).
operationId: startTwoFactorLoginWithId
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFactorStartRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFactorStartResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
tags:
- Two Factor
/api/two-factor/status:
post:
description: Retrieve a user's two-factor status. This can be used to see if a user will need to complete a two-factor challenge to complete a login, and optionally identify the state of the two-factor trust across various applications. This operation provides more payload options than retrieveTwoFactorStatus.
operationId: retrieveTwoFactorStatusWithRequestWithId
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFactorStatusRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFactorStatusResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
tags:
- Two Factor
/api/two-factor/status/{twoFactorTrustId}:
get:
description: Retrieve a user's two-factor status. This can be used to see if a user will need to complete a two-factor challenge to complete a login, and optionally identify the state of the two-factor trust across various applications.
operationId: retrieveTwoFactorStatusWithId
parameters:
- name: userId
in: query
schema:
type: string
description: The user Id to retrieve the Two-Factor status.
- name: applicationId
in: query
schema:
type: string
description: The optional applicationId to verify.
- name: twoFactorTrustId
in: path
schema:
type: string
required: true
description: The optional two-factor trust Id to verify.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFactorStatusResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
tags:
- Two Factor
components:
schemas:
IdentityVerifiedReason:
description: Models the reason that {@link UserIdentity#verified} was set to true or false.
type: string
enum:
- Skipped
- Trusted
- Unverifiable
- Implicit
- Pending
- Completed
- Disabled
- Administrative
- Import
Errors:
description: Standard error domain object that can also be used as the response from an API call.
type: object
properties:
fieldErrors:
type: array
items:
$ref: '#/components/schemas/Error'
generalErrors:
type: array
items:
$ref: '#/components/schemas/Error'
ZonedDateTime:
description: 'The number of milliseconds since the unix epoch: January 1, 1970 00:00:00 UTC. This value is always in UTC.'
example: '1659380719000'
type: integer
format: int64
Locale:
description: A Locale object represents a specific geographical, political, or cultural region.
example: en_US
type: string
ContentStatus:
description: Status for content like usernames, profile attributes, etc.
type: string
enum:
- ACTIVE
- PENDING
- REJECTED
TOTPAlgorithm:
type: string
enum:
- HmacSHA1
- HmacSHA256
- HmacSHA512
MetaData:
type: object
properties:
data:
type: object
additionalProperties:
type: object
device:
$ref: '#/components/schemas/DeviceInfo'
scopes:
type: array
uniqueItems: true
items: {}
UserRegistration:
description: User registration information for a single application.
type: object
properties:
data:
type: object
additionalProperties:
type: object
preferredLanguages:
type: array
items:
$ref: '#/components/schemas/Locale'
tokens:
type: object
additionalProperties:
type: string
applicationId:
type: string
format: uuid
authenticationToken:
type: string
cleanSpeakId:
type: string
format: uuid
id:
type: string
format: uuid
insertInstant:
$ref: '#/components/schemas/ZonedDateTime'
lastLoginInstant:
$ref: '#/components/schemas/ZonedDateTime'
lastUpdateInstant:
$ref: '#/components/schemas/ZonedDateTime'
roles:
type: array
uniqueItems: true
items: {}
timezone:
$ref: '#/components/schemas/ZoneId'
username:
type: string
usernameStatus:
$ref: '#/components/schemas/ContentStatus'
verified:
type: boolean
verifiedInstant:
$ref: '#/components/schemas/ZonedDateTime'
GroupMember:
description: A User's membership into a Group
type: object
properties:
data:
type: object
additionalProperties:
type: object
groupId:
type: string
format: uuid
id:
type: string
format: uuid
insertInstant:
$ref: '#/components/schemas/ZonedDateTime'
userId:
type: string
format: uuid
EventInfo:
description: Information about a user event (login, register, etc) that helps identify the source of the event (location, device type, OS, etc).
type: object
properties:
data:
type: object
additionalProperties:
type: object
deviceDescription:
type: string
deviceName:
type: string
deviceType:
type: string
ipAddress:
type: string
location:
$ref: '#/components/schemas/Location'
os:
type: string
userAgent:
type: string
UserTwoFactorConfiguration:
description: ''
type: object
properties:
methods:
type: array
items:
$ref: '#/components/schemas/TwoFactorMethod'
recoveryCodes:
type: array
items:
type: string
BreachedPasswordStatus:
description: ''
type: string
enum:
- None
- ExactMatch
- SubAddressMatch
- PasswordOnly
- CommonPassword
TwoFactorStartResponse:
description: ''
type: object
properties:
code:
type: string
methods:
type: array
items:
$ref: '#/components/schemas/TwoFactorMethod'
twoFactorId:
type: string
Location:
description: Location information. Useful for IP addresses and other displayable data objects.
type: object
properties:
city:
type: string
country:
type: string
latitude:
type: number
format: double
longitude:
type: number
format: double
region:
type: string
zipcode:
type: string
displayString:
type: string
AuthenticatorConfiguration:
description: ''
type: object
properties:
algorithm:
$ref: '#/components/schemas/TOTPAlgorithm'
codeLength:
type: integer
timeStep:
type: integer
MessageType:
description: ''
type: string
enum:
- SMS
- Voice
UserIdentity:
description: ''
type: object
properties:
displayValue:
type: string
insertInstant:
$ref: '#/components/schemas/ZonedDateTime'
lastLoginInstant:
$ref: '#/components/schemas/ZonedDateTime'
lastUpdateInstant:
$ref: '#/components/schemas/ZonedDateTime'
moderationStatus:
$ref: '#/components/schemas/ContentStatus'
primary:
type: boolean
type:
$ref: '#/components/schemas/IdentityType'
value:
type: string
verified:
type: boolean
verifiedInstant:
$ref: '#/components/schemas/ZonedDateTime'
verifiedReason:
$ref: '#/components/schemas/IdentityVerifiedReason'
Error:
description: Defines an error.
type: object
properties:
code:
type: string
data:
type: object
additionalProperties:
type: object
message:
type: string
IdentityType:
description: Model identity types provided by FusionAuth.
type: object
properties:
name:
type: string
TwoFactorTrust:
type: object
properties:
applicationId:
type: string
format: uuid
expiration:
$ref: '#/components/schemas/ZonedDateTime'
startInstant:
$ref: '#/components/schemas/ZonedDateTime'
TwoFactorSendRequest:
description: ''
type: object
properties:
applicationId:
type: string
format: uuid
email:
type: string
messageType:
$ref: '#/components/schemas/MessageType'
method:
type: string
methodId:
type: string
mobilePhone:
type: string
userId:
type: string
format: uuid
TwoFactorStatusRequest:
description: Check the status of two-factor authentication for a user, with more options than on a GET request.
type: object
properties:
userId:
type: string
format: uuid
accessToken:
type: string
action:
$ref: '#/components/schemas/MultiFactorAction'
applicationId:
type: string
format: uuid
twoFactorTrustId:
type: string
eventInfo:
$ref: '#/components/schemas/EventInfo'
User:
description: The public, global view of a User. This object contains all global information about the user including birthdate, registration information preferred languages, global attributes, etc.
type: object
properties:
preferredLanguages:
type: array
items:
$ref: '#/components/schemas/Locale'
active:
type: boolean
birthDate:
$ref: '#/components/schemas/LocalDate'
cleanSpeakId:
type: string
format: uuid
data:
type: object
additionalProperties:
type: object
email:
type: string
expiry:
$ref: '#/components/schemas/ZonedDateTime'
firstName:
type: string
fullName:
type: string
imageUrl:
type: string
format: URI
insertInstant:
$ref: '#/components/schemas/ZonedDateTime'
lastName:
type: string
lastUpdateInstant:
$ref: '#/components/schemas/ZonedDateTime'
middleName:
type: string
mobilePhone:
type: string
parentEmail:
type: string
phoneNumber:
type: string
tenantId:
type: string
format: uuid
timezone:
$ref: '#/components/schemas/ZoneId'
twoFactor:
$ref: '#/components/schemas/UserTwoFactorConfiguration'
memberships:
type: array
items:
$ref: '#/components/schemas/GroupMember'
registrations:
type: array
items:
$ref: '#/components/schemas/UserRegistration'
identities:
type: array
items:
$ref: '#/components/schemas/UserIdentity'
breachedPasswordLastCheckedInstant:
$ref: '#/components/schemas/ZonedDateTime'
breachedPasswordStatus:
$ref: '#/components/schemas/BreachedPasswordStatus'
connectorId:
type: string
format: uuid
encryptionScheme:
type: string
factor:
type: integer
id:
type: string
format: uuid
lastLoginInstant:
$ref: '#/components/schemas/ZonedDateTime'
password:
type: string
passwordChangeReason:
$ref: '#/components/schemas/ChangePasswordReason'
passwordChangeRequired:
type: boolean
passwordLastUpdateInstant:
$ref: '#/components/schemas/ZonedDateTime'
salt:
type: string
uniqueUsername:
type: string
username:
type: string
usernameStatus:
$ref: '#/components/schemas/ContentStatus'
verified:
type: boolean
verifiedInstant:
$ref: '#/components/schemas/ZonedDateTime'
LoginPreventedResponse:
description: The summary of the action that is preventing login to be returned on the login response.
type: object
properties:
actionId:
type: string
format: uuid
actionerUserId:
type: string
format: uuid
expiry:
$ref: '#/components/schemas/ZonedDateTime'
localizedName:
type: string
localizedOption:
type: string
localizedReason:
type: string
name:
type: string
option:
type: string
reason:
type: string
reasonCode:
type: string
TwoFactorStatusResponse:
description: ''
type: object
properties:
trusts:
type: array
items:
$ref: '#/components/schemas/TwoFactorTrust'
twoFactorTrustId:
type: string
MultiFactorAction:
description: Communicate various actionscontexts in which multi-factor authentication can be used.
type: string
enum:
- changePassword
- login
- stepUp
TwoFactorStartRequest:
description: ''
type: object
properties:
applicationId:
type: string
format: uuid
code:
type: string
loginId:
type: string
loginIdTypes:
type: array
items:
type: string
state:
type: object
additionalProperties:
type: object
trustChallenge:
type: string
userId:
type: string
format: uuid
LocalDate:
description: A date without a time-zone in the ISO-8601 calendar system, such as 2007-12-03.
example: '2007-12-03'
pattern: ^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]$
type: string
ZoneId:
description: Timezone Identifier
example: America/Denver
pattern: ^w+/w+$
type: string
TwoFactorLoginRequest:
description: ''
type: object
properties:
code:
type: string
trustComputer:
type: boolean
twoFactorId:
type: string
userId:
type: string
format: uuid
applicationId:
type: string
format: uuid
ipAddress:
type: string
metaData:
$ref: '#/components/schemas/MetaData'
newDevice:
type: boolean
noJWT:
type: boolean
DeviceInfo:
description: ''
type: object
properties:
description:
type: string
lastAccessedAddress:
type: string
lastAccessedInstant:
$ref: '#/components/schemas/ZonedDateTime'
name:
type: string
type:
type: string
ChangePasswordReason:
description: ''
type: string
enum:
- Administrative
- Breached
- Expired
- Validation
SecretResponse:
description: ''
type: object
properties:
secret:
type: string
secretBase32Encoded:
type: string
TwoFactorMethod:
description: ''
type: object
properties:
authenticator:
$ref: '#/components/schemas/AuthenticatorConfiguration'
email:
type: string
id:
type: string
lastUsed:
type: boolean
method:
type: string
mobilePhone:
type: string
secret:
type: string
LoginResponse:
description: ''
type: object
properties:
actions:
type: array
items:
$ref: '#/components/schemas/LoginPreventedResponse'
changePasswordId:
type: string
changePasswordReason:
$ref: '#/components/schemas/ChangePasswordReason'
configurableMethods:
type: array
items:
type: string
emailVerificationId:
type: string
identityVerificationId:
type: string
methods:
type: array
items:
$ref: '#/components/schemas/TwoFactorMethod'
pendingIdPLinkId:
type: string
refreshToken:
type: string
refreshTokenId:
type: string
format: uuid
registrationVerificationId:
type: string
state:
type: object
additionalProperties:
type: object
threatsDetected:
type: array
uniqueItems: true
items: {}
token:
type: string
tokenExpirationInstant:
$ref: '#/components/schemas/ZonedDateTime'
trustToken:
type: string
twoFactorId:
type: string
twoFactorTrustId:
type: string
user:
$ref: '#/components/schemas/User'
securitySchemes:
ApiKeyAuth:
type: apiKey
name: Authorization
in: header
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT