Download OpenAPI specification:Download
Contains functionality around Contact Identities.
For endpoints that support localization the language can be passed either as a query string parameter (using the name 'language') or in the 'accept-language' header.
If no language is passed to such endpoints then the default configured language will be used.
Retrieves second factor types available for the configured 2FA provider.
Accept-Language | string The ISO 639-1 language to use for localizable data. |
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
{- "secondFactorTypes": [
- {
- "id": 0,
- "name": "string"
}
]
}
Returns key configurations by scope to aid a UI implementing manual input of the key.
scope required | string |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "validForMinutes": 0,
- "length": 0,
- "composition": "Digits"
}
Pre authenticates an account by username and password. Returns different information depending on the 2FA configuration of the contact. Possible reasons of rejection with HTTP 200: PasscodeInvalid, ContactLocked or AccessDenied. Possible scenarios of pair (Status, Factor):
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The pre authentication request which contains the user name, password, trusted device token and a flag to force expiring an existing session on the contact.
userName | string Nullable The contact name based on which authentication will be done. |
password | string Nullable The password of the contact to authenticate. |
trustedDeviceToken | string Nullable If the supplied token is valid, return an “allow” response, meaning that the user does not have to perform secondary authentication as the attempt originates from a trusted device. |
forceExpiringPreviousSession | boolean A flag which indicates if the current existing session of the contact will be expired or not. It is useful when a contact is logged on multiple devices. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "userName": "john.doe@additiv.com",
- "password": "%DR@Ja+G)8cU3Fkr",
- "trustedDeviceToken": "Rm90MWRjdUc0dnhsRHhvM3lELWJhQjRwaV8zbk1tbkZBd2NOZ0sxbVFzZzo1NmYzYTk3NS03YTQwLTQ4MzAtYTcwMC0xMTkyNWM3NDk1ZjM6YXBpLmZ1dHVyYWUuY29t",
- "forceExpiringPreviousSession": true
}
{- "Result": "Success",
- "Status": "Allow",
- "Factor": "Approve",
- "Provider": "Futurae",
- "Length": 6,
- "CampaignContact": {
- "ContactId": 7,
- "UserName": "john.doe@additiv.com",
- "ObfuscatedMobileNumber": "***|*******123",
- "IsActive": true,
- "IsTwoFactorEnabled": false
}, - "Session": {
- "SessionId": "98aa09e032dd4a72a92bf0100d6976c8",
- "JwtAccessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmZjUyNTBhOGM5OTc0NDk4OGFjNjRjZmE2Y2IxNjJkNSIsImlzcyI6IkFkZGl0aXYgQUciLCJzdWIiOiJqZDFAamQuY29tIiwiaWF0IjoxNTI0MDQ0OTUyLCJleHAiOjE1MjQwNDg1NTJ9.KQKCN5CVouVlV0c2SmR1BJxrUr6AD9lWs4lz_qNiNxShsZOStBN8ZgTN20dC2457P90MI2922eFSwtU-G4BXXrLEegCChyXom50jKWI_wsNfXIt2mUD9TEoAXWMO6ITpWNKAm5f1UgPvHsPBh0JJmZ11JWoJkhbQcNjfuXsNra0YAs6D62Znxu-jDDiQWg8hf5379YUEDy6si0XRUXd8mRZ-NIjO_9N_FceabIrJhTelRbr9BrpSY-O929DDv2qBXj7wcLV4i4eZ0z5aotTXWSfjehTGRLgrtOnUOpZycJyqVbEahsOx5KJOwaq0pRZ_l7hOCwncJJ5rernutAjrzA"
}, - "PreAuthenticateSessionId": "b027921e23c447f5ae9e4029c22d737e",
- "GeneratedKey": "9P2D1X"
}
Performs secondary authentication using one of the available factors. The response depends on the chosen factor. If the two-factor authentication is disabled then the session details will be returned and the contact will be automatically authenticated. Possible reasons of rejection with HTTP 200: PasscodeInvalid, ContactLocked or AccessDenied. Possible scenarios of pair (Status, Factor):
contactId required | integer <int32> The contact identifier |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The authentication request which contains the passcode and a flag which establishes a trusted relationship.
passcode | string Nullable The passcode received on the phone or generated by installed application or on the different channels, such as slack. |
setTrusted | boolean If the authentication is successful (i.e., result is allow), also return a trusted device token which can be used in the future to mark the device from which the authentication attempt took place as trusted. |
preAuthenticateSessionId | string Nullable The session identifier of the pre-authentication step. It guarantees the pre-auth has been completed successfully |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "passcode": "211191",
- "setTrusted": true,
- "preAuthenticateSessionId": "b027921e23c447f5ae9e4029c22d737e"
}
{- "Result": "Success",
- "Status": "Allow",
- "Factor": "Approve",
- "TrustedDeviceToken": "Rm90MWRjdUc0dnhsRHhvM3lELWJhQjRwaV8zbk1tbkZBd2NOZ0sxbVFzZzo1NmYzYTk3NS03YTQwLTQ4MzAtYTcwMC0xMTkyNWM3NDk1ZjM6YXBpLmZ1dHVyYWUuY29t",
- "CampaignContact": {
- "ContactId": 7,
- "UserName": "john.doe@additiv.com",
- "IsActive": true,
- "IsTwoFactorEnabled": true
}, - "AuthStatusSessionId": "d80a498d3841464ebef967b056bbc6d6",
- "Session": {
- "SessionId": "f6f6707895e14df0ac647273691e3d7f",
- "JwtAccessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmZjUyNTBhOGM5OTc0NDk4OGFjNjRjZmE2Y2IxNjJkNSIsImlzcyI6IkFkZGl0aXYgQUciLCJzdWIiOiJqZDFAamQuY29tIiwiaWF0IjoxNTI0MDQ0OTUyLCJleHAiOjE1MjQwNDg1NTJ9.KQKCN5CVouVlV0c2SmR1BJxrUr6AD9lWs4lz_qNiNxShsZOStBN8ZgTN20dC2457P90MI2922eFSwtU-G4BXXrLEegCChyXom50jKWI_wsNfXIt2mUD9TEoAXWMO6ITpWNKAm5f1UgPvHsPBh0JJmZ11JWoJkhbQcNjfuXsNra0YAs6D62Znxu-jDDiQWg8hf5379YUEDy6si0XRUXd8mRZ-NIjO_9N_FceabIrJhTelRbr9BrpSY-O929DDv2qBXj7wcLV4i4eZ0z5aotTXWSfjehTGRLgrtOnUOpZycJyqVbEahsOx5KJOwaq0pRZ_l7hOCwncJJ5rernutAjrzA"
}, - "AsynchronousParameters": {
}
}
Checks the authentication status of an account by username and temporary session when async 2FA is enabled. This endpoint can return a response in two different ways:
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The authenticate status request which contains the user name and authentication session.
userName | string Nullable The contact name based on which two factor authentication status is checked. |
authStatusSessionId | string Nullable The identifier to associate the status request with a specific authentication process. It is generated and returned by the endpoint starting the authentication. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "userName": "john.doe@additiv.com",
- "authStatusSessionId": "d80a498d3841464ebef967b056bbc6d6"
}
{- "Result": "Success",
- "TrustedDeviceToken": "Rm90MWRjdUc0dnhsRHhvM3lELWJhQjRwaV8zbk1tbkZBd2NOZ0sxbVFzZzo1NmYzYTk3NS03YTQwLTQ4MzAtYTcwMC0xMTkyNWM3NDk1ZjM6YXBpLmZ1dHVyYWUuY29t",
- "Session": {
- "SessionId": "399645695b7c40a5930de9c531509298",
- "JwtAccessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmZjUyNTBhOGM5OTc0NDk4OGFjNjRjZmE2Y2IxNjJkNSIsImlzcyI6IkFkZGl0aXYgQUciLCJzdWIiOiJqZDFAamQuY29tIiwiaWF0IjoxNTI0MDQ0OTUyLCJleHAiOjE1MjQwNDg1NTJ9.KQKCN5CVouVlV0c2SmR1BJxrUr6AD9lWs4lz_qNiNxShsZOStBN8ZgTN20dC2457P90MI2922eFSwtU-G4BXXrLEegCChyXom50jKWI_wsNfXIt2mUD9TEoAXWMO6ITpWNKAm5f1UgPvHsPBh0JJmZ11JWoJkhbQcNjfuXsNra0YAs6D62Znxu-jDDiQWg8hf5379YUEDy6si0XRUXd8mRZ-NIjO_9N_FceabIrJhTelRbr9BrpSY-O929DDv2qBXj7wcLV4i4eZ0z5aotTXWSfjehTGRLgrtOnUOpZycJyqVbEahsOx5KJOwaq0pRZ_l7hOCwncJJ5rernutAjrzA"
}
}
Authenticates a contact in an SSO scenario using an id-token received from id-server or an external identity provider. An access token will be generated for the contact associated with the external-id detailed in the id-token.
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The SSO authentication request.
idToken | string Nullable The SSO jwt id token. |
provider | string Nullable The external provider name. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmZjUyNTBhOGM5OTc0NDk4OGFjNjRjZmE2Y2IxNjJkNSIsImlzcyI6IkFkZGl0aXYgQUciLCJzdWIiOiJqZDFAamQuY29tIiwiaWF0IjoxNTI0MDQ0OTUyLCJleHAiOjE1MjQwNDg1NTJ9.KQKCN5CVouVlV0c2SmR1BJxrUr6AD9lWs4lz_qNiNxShsZOStBN8ZgTN20dC2457P90MI2922eFSwtU-G4BXXrLEegCChyXom50jKWI_wsNfXIt2mUD9TEoAXWMO6ITpWNKAm5f1UgPvHsPBh0JJmZ11JWoJkhbQcNjfuXsNra0YAs6D62Znxu-jDDiQWg8hf5379YUEDy6si0XRUXd8mRZ-NIjO_9N_FceabIrJhTelRbr9BrpSY-O929DDv2qBXj7wcLV4i4eZ0z5aotTXWSfjehTGRLgrtOnUOpZycJyqVbEahsOx5KJOwaq0pRZ_l7hOCwncJJ5rernutAjrzA",
- "provider": "AAD"
}
{- "Result": "Success",
- "Session": {
- "SessionId": "197ced7994f6452f857fed82fba990ec",
- "JwtAccessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmZjUyNTBhOGM5OTc0NDk4OGFjNjRjZmE2Y2IxNjJkNSIsImlzcyI6IkFkZGl0aXYgQUciLCJzdWIiOiJqZDFAamQuY29tIiwiaWF0IjoxNTI0MDQ0OTUyLCJleHAiOjE1MjQwNDg1NTJ9.KQKCN5CVouVlV0c2SmR1BJxrUr6AD9lWs4lz_qNiNxShsZOStBN8ZgTN20dC2457P90MI2922eFSwtU-G4BXXrLEegCChyXom50jKWI_wsNfXIt2mUD9TEoAXWMO6ITpWNKAm5f1UgPvHsPBh0JJmZ11JWoJkhbQcNjfuXsNra0YAs6D62Znxu-jDDiQWg8hf5379YUEDy6si0XRUXd8mRZ-NIjO_9N_FceabIrJhTelRbr9BrpSY-O929DDv2qBXj7wcLV4i4eZ0z5aotTXWSfjehTGRLgrtOnUOpZycJyqVbEahsOx5KJOwaq0pRZ_l7hOCwncJJ5rernutAjrzA"
}
}
A contact calling this endpoint will log themselves off from the specific session they are in context of the call. An app calling this endpoint will log the contact off from all open sessions.
contactId required | integer <int32> The contact identifier |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "Result": "Success"
}
Retrieves information on the ability of the contact to sign-in. This includes if the sign-in is enabled by the business, if the contact has locked themselves, their password and 2FA state, as well as their last login information. 2FA device information will be returned if 2FA provider supports device enrollment.
contactId required | integer <int32> The contact identifier |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "IsSignInEnabled": false,
- "IsPasswordSet": true,
- "IsSecondFactorEnabled": false,
- "HasEnrolledDevices": true,
- "IsSignInLocked": false,
- "LockoutFactor": "DFSAuthSecondFactor",
- "LockoutExpireDate": "2024-09-23T15:43:06.7091677Z",
- "LastLoginDate": "2024-09-23T15:43:06.7091672Z",
- "SecondFactorType": {
- "id": 10,
- "name": "Approve"
}
}
Updates contact second-factor settings for authentication. The contact needs to have sign-in enabled and password set.
contactId required | integer <int32> The contact identifier. |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
Second factor payload
isSecondFactorEnabled | boolean Nullable |
secondFactorTypeId | integer <int32> Nullable |
No Content
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "isSecondFactorEnabled": true,
- "secondFactorTypeId": 0
}
{- "code": "General",
- "subCode": "string",
- "message": "string",
- "correlationId": "string",
- "properties": {
- "property1": null,
- "property2": null
}
}
Enables contact sign-in ability to DFS.
contactId required | integer <int32> The ID of the contact to enable |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
No Content
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "code": "General",
- "subCode": "string",
- "message": "string",
- "correlationId": "string",
- "properties": {
- "property1": null,
- "property2": null
}
}
Enables contact sign-in ability through key validation which was sent to the contact. If DFS is the identity provider, response will be populated with information relevant for the next steps following activation.
key required | string The key of the contact to activate |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "contactId": 0,
- "username": "string",
- "isPasswordSet": true
}
Disables contact sign-in ability to DFS. The contact will also be logged out of all open sessions and all their devices will be un-enrolled.
contactId required | integer <int32> The ID of the contact to deactivate |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
No Content
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "code": "General",
- "subCode": "string",
- "message": "string",
- "correlationId": "string",
- "properties": {
- "property1": null,
- "property2": null
}
}
Sends a key (EnableSignIn and FirstTimePassword scopes) to the selected contact’s channel. This key may be used to enable contact’s sign-in ability to DFS, as well as help set the first password. Caller may override default enable-sign-in redirect URL.
contactId required | integer <int32> |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
redirectUrl | string Nullable |
channel | string (CommunicationChannel) Enum: "Email" "Mobile" |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "redirectUrl": "string",
- "channel": "Email"
}
{- "GeneratedKey": "7B2C4E"
}
Unlocks a contact that was locked due to multiple failed authentication attempts (passcode or mTan). If the contact is not locked an HTTP 200 with Result = ContactAlreadyUnlocked will be returned.
contactId required | integer <int32> The contact identifier |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "Result": "Success"
}
Provides an API a Futurae server can call in order to deliver status updates as well as the result of a particular authentication attempt (also called authentication session). The URL will be called as a POST request with "Content-Type" header being "application/json". The body of the request will be a JSON object containing the following keys and corresponding values: user_id, username, session_id, result, status, status_msg and trusted_device_token. The session ID identifies the particular authentication session and is conditionally returned by /v1.1/authentication/authenticate endpoint.
authorization | string The tenant hash identifier |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The authentication request which contains information about authentication session status.
username | string Nullable The contact name based on which authentication will be done. |
user_id | string Nullable The user identifier linked to the UserName used by 2FA provider. |
session_id | string Nullable A session ID that identifies the newly created authentication session. It can be used to receive real-time updates regarding the status of the authentication session. |
trusted_device_token | string Nullable A token that can be used to mark the device from which the authentication attempt took place as trusted. This can later be passed to the /authentication/preauthenticate endpoint, in order to immediately grant access (without performing secondary authentication), in case the authentication attempt originates from this device. |
result | string (SecondFactorResult) Enum: "Allow" "Auth" "Deny" "Waiting" "Unknown" "Success" "Expired" "Pending" "Disabled" "Locked" "InvalidPasscode" "Success2FaDisabled" |
status | string Nullable The authentication status: bypass, disabled, locked_out. |
status_msg | string Nullable The authentication status message. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "username": "john.doe@additiv.com",
- "user_id": "337317c6-f40e-4253-9f15-075ee3e61760",
- "session_id": "8d37c56d-61a9-4998-b118-b42baff74174",
- "trusted_device_token": "Rm90MWRjdUc0dnhsRHhvM3lELWJhQjRwaV8zbk1tbkZBd2NOZ0sxbVFzZzo1NmYzYTk3NS03YTQwLTQ4MzAtYTcwMC0xMTkyNWM3NDk1ZjM6YXBpLmZ1dHVyYWUuY29t",
- "result": "Allow",
- "status": "",
- "status_msg": "Authenticated"
}
{- "Result": "Success"
}
Provides an API a Futurae server can call in order to inform the application when the enrollment was successfully completed. The body of the request will be a JSON object containing the following keys and corresponding values: user_id, username, activation_code and result. The value of the latter will always be "success", since the callback will only be called when the enrollment is completed successfully.
authorization | string The tenant hash identifier |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The enrollment request which contains the result of the enrollment process.
device_id | string Nullable The contact device-id based on which enrollment will be done. |
username | string Nullable The contact name based on which enrollment will be done. |
user_id | string Nullable The user identifier linked to the UserName used by 2FA provider. |
activation_code | string Nullable The activation code used to complete the enrollment of the device. |
result | string Nullable The result status. The value of the latter will always be “success”, since the callback will only be called when the enrollment is completed successfully. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "device_id": "f71c2c34-7521-4878-82a7-be47972e7298",
- "username": "john.doe@additiv.com",
- "user_id": "56f3a975-7a40-4830-a700-11925c7495f3",
- "activation_code": "futurae://enroll?activation_code=Rm90MWRjdUc0dnhsRHhvM3lELWJhQjRwaV8zbk1tbkZBd2NOZ0sxbVFzZzo1NmYzYTk3NS03YTQwLTQ4MzAtYTcwMC0xMTkyNWM3NDk1ZjM6YXBpLmZ1dHVyYWUuY29t",
- "result": "Success"
}
{- "Result": "Success"
}
Returns the list of password policies with the details (including settings)
Accept-Language | string The ISO 639-1 language to use for localizable data. |
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
{- "Policies": [
- {
- "Name": "uppercasechars",
- "Description": "The password must contain at least 1 upper-case character"
}, - {
- "Name": "minlength",
- "Description": "The password must be at least 3 characters long",
- "Settings": [
- {
- "Key": "MinLength",
- "Value": 3
}
]
}, - {
- "Name": "regularexpression",
- "Description": "The password must match the following pattern: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[@$!%*?&])[A-Za-z\\d@$!%*?&]{8,}$",
- "Settings": [
- {
- "Key": "RegularExpression",
- "Value": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[@$!%*?&])[A-Za-z\\d@$!%*?&]{8,}$"
}
]
}
]
}
Updates contact password given the old password. The new password is validated against the contact password policies.
contactId required | integer <int32> The contact identifier |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The update contact password request
oldPassword | string Nullable |
newPassword | string Nullable |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "oldPassword": "string",
- "newPassword": "string"
}
{- "ValidationResult": {
- "IsValid": true,
- "Policies": [
- {
- "Policy": "string",
- "IsValid": true
}
]
}, - "Result": "Success"
}
Triggers a forgotten password flow based on username/email (username takes priority if both provided). In this first step, a key (ForgotPassword scope) is sent to the mobile of the contact, and a session is generated and returned (to be validated together in the next step). The endpoint will return success even if it cannot find a contact, or the contact found is deactivated.
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The trigger forgotten password request
string Nullable Email of the contact for which the password needs to be reset. If email is not unique, the operation would fail. | |
username | string Nullable Username of the contact for which the password needs to be reset. If supplied alongside email information, this will take priority. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "email": "string",
- "username": "string"
}
{- "GeneratedSessionId": "string",
- "GeneratedKey": "string"
}
Sends a key (ResetPassword scope) to the email of the contact as a second step of the forgotten password flow, after preliminary-key and session are validated successfully. If a reset-password key is successfully sent to the contact, the current password can no longer be used. Caller may override default reset-password redirect URL.
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The send reset password key request
preliminaryKey | string Nullable |
sessionId | string Nullable |
redirectUrl | string Nullable |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "preliminaryKey": "string",
- "sessionId": "string",
- "redirectUrl": "string"
}
{- "Result": "Success",
- "GeneratedKey": "string"
}
Resets contact password through key validation which was sent to the contact. Key may be a reset-password key generated by the forgotten password flow or sent directly by the member, or it may be a first-time-password key generated when indirectly enabling contact sign-in ability. The new password is validated against the contact password policies, aside from password-history policy.
key required | string The key |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The reset password request
password | string Nullable |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "password": "string"
}
{- "ValidationResult": {
- "IsValid": true,
- "Policies": [
- {
- "Policy": "string",
- "IsValid": true
}
]
}, - "Result": "Success"
}
Sends a key (ResetPassword scope) to the selected contact’s channel. If a key is successfully sent to the contact, the current password can no longer be used. Caller may override default reset-password redirect URL.
contactId required | integer <int32> The contact identifier |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The reset password request
redirectURL | string Nullable |
channel | string (CommunicationChannel) Enum: "Email" "Mobile" |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "redirectURL": "string",
- "channel": "Email"
}
{- "generatedKey": "string"
}
Retrieves contact’s enrolled devices used for second factor authentication.
contactId required | integer <int32> The contact identifier for which the enrolled devices will be returned. |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "Results": [
- {
- "deviceUid": "79a1857a-e6ad-4651-9ddc-2b49c349d803",
- "enrollmentDate": "2024-09-23T15:43:07.0107794Z",
- "isActive": true
}
]
}
This API is used only in the context of an authenticated account (it requires a JWT token), when the account activates 2FA. If the enrollment is not required for the set factor, then the 2FA is enabled for that contact and it returns a Success response. If the enrollment is required for the set factor, then starts the enrollment of a user device using the specific two-factor which is set in the database. This is the first step of the enrollment process. If it is successful, then an ActivationQrCodeUrl is returned in the response. The end-user will scan the qr code using the mobile app (e.g. Futurae). If the enrollment is successful, then the 2FA provider will post the final result, the user identification and the activation code using the callback set in the database. The callback will post the request using api enrollment/complete.
contactId required | integer <int32> The contact identifier for which the device will be enrolled. |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "Result": "Success",
- "UserName": "john.doe@additiv.com",
- "EnrollmentSessionId": "28ffa3b8dfe644a7ba4f26a787a7e2e0",
- "AsynchronousParameters": {
}
}
Starts the enrollment process of an unauthenticated contact for the contact's device using the specific two-factor provider defined in the system settings. If this first step is successful (provided credentials are valid), and device enrollment is required (depending on the 2FA provider), then an ActivationQrCodeUrl is returned in the response. Then end-user is required to scan the verification QR code using the mobile app (e.g. Futurae). If the scan step is successful, then the 2FA provider will post the final result, the user identification and the activation code using a callback method configured for the provider. You may use this endpoint both if 2FA is disabled for the contact (successful process will enable it) or if 2FA is already enabled for the contact but no device is enrolled.
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The enrollment request which contains the user name and password in order to authenticate the contact.
userName | string Nullable The contact name based on which enrollment will be done. |
password | string Nullable The password of the contact to enroll. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "userName": "john.doe@additiv.com",
- "password": "%DR@Ja+G)8cU3Fkr"
}
{- "Result": "Success",
- "UserName": "john.doe@additiv.com",
- "EnrollmentSessionId": "b4edfac79c924455853840cd227afd8b",
- "AsynchronousParameters": {
}
}
Checks whether a user has a completed enrollment. The endpoint returns immediately with the current enrollment status, thus you would need to use this endpoint on a poll-based fashion, in order to get informed about a status update. If polling is necessary, we strongly recommend polling no faster than every 1-3 seconds.
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The complete enrollment request.
userName | string Nullable The contact name based on which enrollment will be done. |
enrollmentSessionId | string Nullable The identifier to associate the status request with a specific enrollment process. It is generated and returned by the endpoint starting the enrollment. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "userName": "john.doe@additiv.com",
- "enrollmentSessionId": "1ebbedb9987d4e189d837fad4114e7d0"
}
{- "Result": "Success",
- "Status": "Pending"
}
Unenrolls (deactivate) the latest enrolled device of a user. If this was the only device enrolled for the contact, 2FA is enabled for that contact, and the 2FA provider requires a device, the contact would need to enroll a new device before being able to log in. In context of this call, 2FA may also be disabled for the contact
contactId required | integer <int32> The contact identifier for which the enrolled device will be unenrolled. |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The unenrollment request which contain the flag which indicates whether the two factor flag of the contact will be disabled or not.
disableTwoFactor | boolean Nullable The flag which indicates whether the two factor flag of the contact will be disabled or not. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "disableTwoFactor": true
}
{- "Result": "Success"
}
Gets a JWT token for a given sessionId.
contactId required | integer <int32> The ID of the contact that the token belongs to. |
sessionId required | string The session identifier. |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "Result": "Success",
- "Session": {
- "SessionId": "044651ed0ca24b5aa832433d10fe1a8f",
- "JwtAccessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmZjUyNTBhOGM5OTc0NDk4OGFjNjRjZmE2Y2IxNjJkNSIsImlzcyI6IkFkZGl0aXYgQUciLCJzdWIiOiJqZDFAamQuY29tIiwiaWF0IjoxNTI0MDQ0OTUyLCJleHAiOjE1MjQwNDg1NTJ9.KQKCN5CVouVlV0c2SmR1BJxrUr6AD9lWs4lz_qNiNxShsZOStBN8ZgTN20dC2457P90MI2922eFSwtU-G4BXXrLEegCChyXom50jKWI_wsNfXIt2mUD9TEoAXWMO6ITpWNKAm5f1UgPvHsPBh0JJmZ11JWoJkhbQcNjfuXsNra0YAs6D62Znxu-jDDiQWg8hf5379YUEDy6si0XRUXd8mRZ-NIjO_9N_FceabIrJhTelRbr9BrpSY-O929DDv2qBXj7wcLV4i4eZ0z5aotTXWSfjehTGRLgrtOnUOpZycJyqVbEahsOx5KJOwaq0pRZ_l7hOCwncJJ5rernutAjrzA"
}
}
Validates a provided JWT access token (expiration, contactId, memberId, subject, auditContextId). Returns the result type of the validation (Success or one of the invalid result types).
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The validate token request
accessToken | string Nullable The JWT access token that will be validated. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI3NTIzMzE0YjU4ZDU0YTQxYTA1YzI2NDA4MmQzZDRlMiIsImlzcyI6IkFkZGl0aXYgQUciLCJzdWIiOiJzdGVsaWFuLmR1bWl0cmEiLCJpYXQiOjE1NDY4NTg4OTYsImV4cCI6MTU0Njg2MDA5NiwiY2lkIjoxMjM0LCJtaWQiOjB9.VA3Qlfs8tzqryo6imIyZ7vcRDipDI71W_7O6seuojhvoiWom8r0mQMIzgfzTB01CXFvBpx-BhfzODFT1bPsqSoSMdMEiwqMQA3TzaWDfkFmsfQ6ZEx9D7PbUD6TtHj8IrJFrIwlPBlRDuUXPz6lOxdaGMQxmpQagtLi-5NWmQPrj4WjmEvzDLcuWyjWZAuLqTr1xabVGYyZd-kb2dENaDdcjb73jsyw89ChnYii_5j81-mcudouwPIdm5ECvKBW5G2Anbi0ITwusS9eHGd7bx5JAJYKtpt8o2hk4VLC5qx4S6jCn0sTEiB5Kz5FxgFeAHfYesIPOY7SYTLPmF1A7Xw"
}
{- "Result": "Success"
}
Renews an expired or existing session/JWT token. Returns the renewed JWT token along with session id.
contactId required | integer <int32> The contact identifier |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The renew token request
accessToken | string Nullable The access token that will be renewed. |
OK
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Internal Server Error
{- "accessToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjUxMThGM0YxRkRDMDcyRjAwNjA2NzU5NjY3N0NEQTNFIiwidHlwIjoiYXQrand0In0.eyJuYmYiOjE2MTM1NTQwMzMsImV4cCI6MTYxMzU1NzYzMywiaXNzIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6NDQzNTIiLCJhdWQiOlsiSWRlbnRpdHlTZXJ2ZXJBcGkiLCJTZXJ2aWNlTGF5ZXJBcGkiLCJBZG1pblNlcnZpY2VBcGkiLCJEbXNTZXJ2aWNlQXBpIiwiQWxlcnRpbmdTZXJ2aWNlQXBpIiwiU3RhbmRhcmRUYXNrc0FwaSIsIkVuZ2FnZW1lbnRDb250ZW50QXBpIiwiTWlzU2VydmljZXNBcGkiLCJEeW5hbWljQ2xpZW50U2VydmljZXNBcGkiLCJBbGVydGluZ0xpc3RlbmVyQXBpIiwiVGFza0F1dG9tYXRpb25BcGkiXSwiY2xpZW50X2lkIjoiS3QyYWNBVTRFUEF0a1N3dEY0WVozYUNKNWZmREFIIiwiYWNpZCI6Ii0zIiwidHVpZCI6ImFmNGM3OWIyLTVlZGQtNGZiMi1iOWRmLTM1ODRhNTk0MWZlYiIsInRpZCI6IjIiLCJ0a3kiOiJBZGRpdGl2IiwianRpIjoiOURERjY3QzFGMEZBMDBBQkQzRDI3MjQ5REZFRjEzOTgiLCJpYXQiOjE2MTM1NTQwMzMsInNjb3BlIjpbImFwcF9pbXBlcnNvbmF0aW9uIiwiRGZzQXBpIl19.mIeMWRj0Kgj3op2462aLIw_5oBFZxU5GJAV1rTmZhq-2LrwagiqKGQ5bizGKRdW8DcGvLKtMxzfp3RxpqxT9yZyzO5SBxswxJAt1KW-LOQmIh60fCJUfKm53BkkhEgESAx8vplGdHqGzKx4St8YpTB7Wl8_-7QNvf8po5IBNKKCXnRGFLmiM2aNVSHZTc6hQB4phI5astDOIupZWYPrZkhNa6WP11fb9XEi2h7gVeVT_pSZbufckah8bRV0-YYo2kO9ZTDZJRCkZ3TPwNDW8CxvFQyUj2gP3lQiM1yYblMKSVDvIncrENw9A53hbCN9xcpEJhO2dfU3gtGHtx39dfg"
}
{- "Result": "Success",
- "Session": {
- "SessionId": "b2406f2859b24923ab8467384df04e1a",
- "JwtAccessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmZjUyNTBhOGM5OTc0NDk4OGFjNjRjZmE2Y2IxNjJkNSIsImlzcyI6IkFkZGl0aXYgQUciLCJzdWIiOiJqZDFAamQuY29tIiwiaWF0IjoxNTI0MDQ0OTUyLCJleHAiOjE1MjQwNDg1NTJ9.KQKCN5CVouVlV0c2SmR1BJxrUr6AD9lWs4lz_qNiNxShsZOStBN8ZgTN20dC2457P90MI2922eFSwtU-G4BXXrLEegCChyXom50jKWI_wsNfXIt2mUD9TEoAXWMO6ITpWNKAm5f1UgPvHsPBh0JJmZ11JWoJkhbQcNjfuXsNra0YAs6D62Znxu-jDDiQWg8hf5379YUEDy6si0XRUXd8mRZ-NIjO_9N_FceabIrJhTelRbr9BrpSY-O929DDv2qBXj7wcLV4i4eZ0z5aotTXWSfjehTGRLgrtOnUOpZycJyqVbEahsOx5KJOwaq0pRZ_l7hOCwncJJ5rernutAjrzA"
}
}