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.
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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 |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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 an account through an id-server issued token containing information on contact’s external-id. If external-id provided is not unique, system input must be provided as well.
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The SSO authentication request.
accessToken | string Nullable The SSO jwt access token. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmZjUyNTBhOGM5OTc0NDk4OGFjNjRjZmE2Y2IxNjJkNSIsImlzcyI6IkFkZGl0aXYgQUciLCJzdWIiOiJqZDFAamQuY29tIiwiaWF0IjoxNTI0MDQ0OTUyLCJleHAiOjE1MjQwNDg1NTJ9.KQKCN5CVouVlV0c2SmR1BJxrUr6AD9lWs4lz_qNiNxShsZOStBN8ZgTN20dC2457P90MI2922eFSwtU-G4BXXrLEegCChyXom50jKWI_wsNfXIt2mUD9TEoAXWMO6ITpWNKAm5f1UgPvHsPBh0JJmZ11JWoJkhbQcNjfuXsNra0YAs6D62Znxu-jDDiQWg8hf5379YUEDy6si0XRUXd8mRZ-NIjO_9N_FceabIrJhTelRbr9BrpSY-O929DDv2qBXj7wcLV4i4eZ0z5aotTXWSfjehTGRLgrtOnUOpZycJyqVbEahsOx5KJOwaq0pRZ_l7hOCwncJJ5rernutAjrzA"
}
{- "Result": "Success",
- "Session": {
- "SessionId": "197ced7994f6452f857fed82fba990ec",
- "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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "Result": "Success"
}
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "Result": "Success"
}
Checks whether a contact is locked due to multiple failed authentication attempts (passcode or mTan) and retrieves his status.
contactId required | integer <int32> The contact identifier |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "IsPasscodeLocked": true,
- "IsMTanLocked": false,
- "IsTwoFactorLocked": false,
- "AccountStatusCode": "IsActive"
}
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "IsSignInEnabled": false,
- "IsPasswordSet": true,
- "IsSecondFactorEnabled": false,
- "HasEnrolledDevices": true,
- "IsSignInLocked": false,
- "LockoutFactor": "DFSAuthSecondFactor",
- "LockoutExpireDate": "2023-05-24T06:59:49.8249605Z",
- "LastLoginDate": "2023-05-24T06:59:49.82496Z"
}
Changes the two-factor flag of a campaign contact in order to allow/disallow the second factor in an authentication process.
contactId required | integer <int32> The contact identifier. |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
Two factor payload containing the flag which enables/disables authentication via 2FA
isTwoFactorEnabled | boolean |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "isTwoFactorEnabled": true
}
{- "Result": "Success"
}
Changes the two-factor flag of a campaign contact in order to allow/disallow the second factor in an authentication process.
contactId required | integer <int32> The contact identifier. |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
Two factor payload containing the flag which enables/disables authentication via 2FA
isTwoFactorEnabled | boolean |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "isTwoFactorEnabled": true
}
{- "Result": "Success"
}
This API is deprecated. Use POST /v1.0/contacts/{contactId}/sign-in/enable instead
Activates a contact directly. An activated contact can log in to a client facing app.
contactId required | integer <int32> The ID of the contact to activate |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
No Content
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "code": "BadRequest",
- "subCode": "NA",
- "message": "The request was not in the required format",
- "correlationId": "30d3ebc0b5cb47b0889850bbdfe4aec6"
}
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
Server Error
{- "code": "BadRequest",
- "subCode": "NA",
- "message": "The request was not in the required format",
- "correlationId": "30d3ebc0b5cb47b0889850bbdfe4aec6"
}
This API is deprecated. Use POST /v1.0/contacts/sign-in/enable/{key} instead
Activates a contact using an activation key. If DFS is the identity provider, response will be populated with
information relevant for the next steps following activation.
activationKey required | string The activationKey of the contact to activate |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "contactId": 0,
- "username": "string",
- "isPasswordSet": true
}
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "contactId": 0,
- "username": "string",
- "isPasswordSet": true
}
This API is deprecated. Use POST /v1.0/contacts/{contactId}/sign-in/disable instead
Deactivates a contact. The contact will also be logged out of all open sessions and all their devices will be
un-enrolled. A deactivated contact cannot log in to a client facing app.
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
Server Error
{- "code": "BadRequest",
- "subCode": "NA",
- "message": "The request was not in the required format",
- "correlationId": "30d3ebc0b5cb47b0889850bbdfe4aec6"
}
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
Server Error
{- "code": "BadRequest",
- "subCode": "NA",
- "message": "The request was not in the required format",
- "correlationId": "30d3ebc0b5cb47b0889850bbdfe4aec6"
}
This API is deprecated. Use POST /v1.0/contacts/{contactId}/sign-in/enable/send-key instead
Sends an email to a contact with a redirect URL and a generated key. This key may be used to activate the contact, as well as help set the first password. An activated contact can log in to a client facing app.
contactId required | integer <int32> The ID of the contact to send the activation email to |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The parameter DTO
activationUrl | string Nullable Optional base URL that is used to compose the actual activation link sent in the email. If not specified then the DB dbo.GlobalSettings value 'FrontOfficeActivationContactUrl' in group 'Urls' will be used. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "activationUrl": "string"
}
{- "GeneratedKey": "9P2D1X"
}
Sends an email or SMS to a contact with a redirect URL and a generated key. 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" |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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 (additiv.Identity.TwoFactor.Models.Payloads.ResultType) 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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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. |
Success
Bad Request
Unauthorized
Forbidden
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 |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "oldPassword": "string",
- "newPassword": "string"
}
{- "ValidationResult": {
- "IsValid": true,
- "Policies": [
- {
- "Policy": "string",
- "IsValid": true
}
]
}, - "Result": "Success"
}
Triggers a forgotten password process based on username or email. The username takes the priority over email to identify the campaign contact if both are provided. If the contact is registered, then the details of the campaign contact are returned and an mTan is generated and sent to the contact.
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The forgotten password request
string Nullable The email for which the password was forgotten. | |
userName | string Nullable The user name for which the password was forgotten. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "email": "john.doe@additiv.com",
- "userName": "john.doe@additiv.com"
}
{- "SessionId": "10230448c09f43dc85776b458431e405",
- "GeneratedKey": "9P2D1X"
}
Sends a forgotten password activation link by email to the given contactId provided that the contact exists, is active and for that the given mtan and sessionId are valid. After this call, the previous password, if existing, can no longer be used and the contact can log-in again only after setting a new password. If the system is in testing mode, due to testing reasons, the new generated activation key is returned. It can be used later in the reset password flow.
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The forgotten password mtan request
mTan | string Nullable The mTan code received on the phone or on the different channels, such as slack. |
redirectUrl | string Nullable optional - The front office redirect url that will be sent to the contact email once the mTan is validated in order to set a new password. If not specified in the request then it will be taken from the application setting. If both are defined, the request value take precedence. Only provide the url in the request if different clients (e.g. different mobile OS Apps) require different urls. |
sessionId | string Nullable The unique session identifier obtained during first flow in order to hide sensitive information about the involved contact. It is null (not used) in v1 endpoints, but is required starting with v2 endpoints. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "mTan": "9d5s2g2q6",
- "sessionId": "fac7cfe0015f4c22be008a95038c82c7"
}
{- "Result": "Success",
- "GeneratedKey": "bb34f8e3"
}
Sets a password for an existing, active contact which is not authenticated based on the provided activation key. Can be used for first password creation or for password reset as long as the contact is active already. If the activation key is valid, the new password is set for the contact. Once the password is set the contact should be redirected to a login page and use the new password. The new password is validated against the contact password policies. If it fails, the details about the validated polices are returned. The password-history policy is not relevant for this endpoint therefore is not executed.
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The reset password request
activationKey | string Nullable The activation key used to validate the contact. |
password | string Nullable The new password. |
confirmPassword | string Nullable The new password confirmed. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "activationKey": "bb34f8e3-6863-48bd-b203-3442f54ee684",
- "password": "n3wP@$sw0rd",
- "confirmPassword": "n3wP@$sw0rd"
}
{- "ValidationResult": {
- "IsValid": false,
- "Policies": [
- {
- "Policy": "uppercasechars",
- "IsValid": true
}, - {
- "Policy": "regularexpression",
- "IsValid": false
}, - {
- "Policy": "passwordhistory",
- "IsValid": true
}, - {
- "Policy": "minlength",
- "IsValid": true
}
]
}, - "Result": "PasswordPolicyValidationFailed"
}
Sets a new password for an existing, active contact with password set which is authenticated based on the contact id provided. The new password is validated against the contact password policies. If it fails, the details about the validated polices are returned.
contactId required | integer <int32> The contact identifier |
Accept-Language | string The ISO 639-1 language to use for localizable data. |
The reset password request
oldPassword | string Nullable The old password. |
password | string Nullable The new password. |
confirmPassword | string Nullable The new password confirmed. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "oldPassword": "0ldP4$$w0rD",
- "password": "n3wP@$sw0rd",
- "confirmPassword": "n3wP@$sw0rd"
}
{- "ValidationResult": {
- "IsValid": false,
- "Policies": [
- {
- "Policy": "uppercasechars",
- "IsValid": true
}, - {
- "Policy": "regularexpression",
- "IsValid": false
}, - {
- "Policy": "passwordhistory",
- "IsValid": true
}, - {
- "Policy": "minlength",
- "IsValid": true
}
]
}, - "Result": "PasswordPolicyValidationFailed"
}
Triggers a forgotten password flow based on username/email (username takes priority if both provided). In this first step, a key 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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "email": "string",
- "username": "string"
}
{- "GeneratedSessionId": "string",
- "GeneratedKey": "string"
}
Sends a reset-password key 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 |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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 |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "password": "string"
}
{- "ValidationResult": {
- "IsValid": true,
- "Policies": [
- {
- "Policy": "string",
- "IsValid": true
}
]
}, - "Result": "Success"
}
Sends a reset-password key. 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.
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" |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
Server Error
{- "Results": [
- {
- "deviceUid": "79a1857a-e6ad-4651-9ddc-2b49c349d803",
- "enrollmentDate": "2023-05-24T06:59:49.8898196Z",
- "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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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. |
Success
Bad Request
Unauthorized
Forbidden
Not Found
UnprocessableEntity
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"
}
}