Loading

DFS Contact Identity Services API (latest)

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.

Authentication

Retrieve second factor supported types

Retrieves second factor types available for the configured 2FA provider.

Authorizations:
header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

get/v1.0/authentication/second-factor
https://example-host/v1.0/authentication/second-factor

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "secondFactorTypes":
    [
    ]
}

Return key configurations by scope

Returns key configurations by scope to aid a UI implementing manual input of the key.

Authorizations:
path Parameters
scope
required
string
header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

get/v1.0/settings/key-scopes/{scope}
https://example-host/v1.0/settings/key-scopes/{scope}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "validForMinutes": 0,
  • "length": 0,
  • "composition": "Digits"
}

Pre authenticate

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):

  • Auth - Passcode - The user is eligible for secondary authentication. Authenticate endpoint must be called as the secondary step with passcode as input (obtained through mtan or 2FA application).
  • Auth - Approve - The user is eligible for secondary authentication. Authenticate endpoint must be called as the secondary step.
  • Auth - QrCode - The user is eligible for secondary authentication. Authenticate endpoint must be called as the secondary step.
  • Allow - The user is configured to bypass secondary authentication or is authenticating from a trusted device. The session details are returned, and the user will be authenticated without a secondary step.
Authorizations:
header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

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.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.1/authentication/pre-authenticate
https://example-host/v1.1/authentication/pre-authenticate

Request samples

Content type
Copy
Expand all Collapse all
{
  • "userName": "john.doe@additiv.com",
  • "password": "%DR@Ja+G)8cU3Fkr",
  • "trustedDeviceToken": "Rm90MWRjdUc0dnhsRHhvM3lELWJhQjRwaV8zbk1tbkZBd2NOZ0sxbVFzZzo1NmYzYTk3NS03YTQwLTQ4MzAtYTcwMC0xMTkyNWM3NDk1ZjM6YXBpLmZ1dHVyYWUuY29t",
  • "forceExpiringPreviousSession": true
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success",
  • "Status": "Allow",
  • "Factor": "Approve",
  • "Provider": "Futurae",
  • "Length": 6,
  • "CampaignContact":
    {
    },
  • "Session":
    {
    },
  • "PreAuthenticateSessionId": "b027921e23c447f5ae9e4029c22d737e",
  • "GeneratedKey": "9P2D1X"
}

Authenticate

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):

  • Allow - Passcode - The session details are returned and the user will be authenticated.
  • Allow - Approve - The session details are returned and the user will be authenticated.
  • Auth / NULL - Approve - The end-user will approve or reject the authentication request via a 2FA mobile app.
  • Auth / NULL - QrCode - The end-user will scan the code received (as URL). For Auth status a temporary session is returned in order to allow status requests on the current authentication process. A callback is pending to be called by a 2FA provider to complete the authentication.
Authorizations:
path Parameters
contactId
required
integer <int32>

The contact identifier

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

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

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.1/contacts/{contactId}/authentication/authenticate
https://example-host/v1.1/contacts/{contactId}/authentication/authenticate

Request samples

Content type
Copy
Expand all Collapse all
{
  • "passcode": "211191",
  • "setTrusted": true,
  • "preAuthenticateSessionId": "b027921e23c447f5ae9e4029c22d737e"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success",
  • "Status": "Allow",
  • "Factor": "Approve",
  • "TrustedDeviceToken": "Rm90MWRjdUc0dnhsRHhvM3lELWJhQjRwaV8zbk1tbkZBd2NOZ0sxbVFzZzo1NmYzYTk3NS03YTQwLTQ4MzAtYTcwMC0xMTkyNWM3NDk1ZjM6YXBpLmZ1dHVyYWUuY29t",
  • "CampaignContact":
    {
    },
  • "AuthStatusSessionId": "d80a498d3841464ebef967b056bbc6d6",
  • "Session":
    {
    },
}

Authenticate status

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:

  • It can wait until the authentication session has been completed and return when the result is available.
  • It can wait just for the next status update during the authentication session and return the new status. It can then be called once again to either retrieve the next status update or wait for the result to become available (depending on how it’s called this time). If the response is successful session details will be returned and the contact will be able to authenticate.
Authorizations:
header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

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.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.1/authentication/authenticate/status
https://example-host/v1.1/authentication/authenticate/status

Request samples

Content type
Copy
Expand all Collapse all
{
  • "userName": "john.doe@additiv.com",
  • "authStatusSessionId": "d80a498d3841464ebef967b056bbc6d6"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success",
  • "TrustedDeviceToken": "Rm90MWRjdUc0dnhsRHhvM3lELWJhQjRwaV8zbk1tbkZBd2NOZ0sxbVFzZzo1NmYzYTk3NS03YTQwLTQ4MzAtYTcwMC0xMTkyNWM3NDk1ZjM6YXBpLmZ1dHVyYWUuY29t",
  • "Session":
    {
    }
}

Authenticate a contact using an external id-token

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.

Authorizations:
header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

The SSO authentication request.

idToken
string Nullable

The SSO jwt id token.

provider
string Nullable

The external provider name.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.1/authentication/authenticate/sso
https://example-host/v1.1/authentication/authenticate/sso

Request samples

Content type
Copy
Expand all Collapse all
{
  • "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmZjUyNTBhOGM5OTc0NDk4OGFjNjRjZmE2Y2IxNjJkNSIsImlzcyI6IkFkZGl0aXYgQUciLCJzdWIiOiJqZDFAamQuY29tIiwiaWF0IjoxNTI0MDQ0OTUyLCJleHAiOjE1MjQwNDg1NTJ9.KQKCN5CVouVlV0c2SmR1BJxrUr6AD9lWs4lz_qNiNxShsZOStBN8ZgTN20dC2457P90MI2922eFSwtU-G4BXXrLEegCChyXom50jKWI_wsNfXIt2mUD9TEoAXWMO6ITpWNKAm5f1UgPvHsPBh0JJmZ11JWoJkhbQcNjfuXsNra0YAs6D62Znxu-jDDiQWg8hf5379YUEDy6si0XRUXd8mRZ-NIjO_9N_FceabIrJhTelRbr9BrpSY-O929DDv2qBXj7wcLV4i4eZ0z5aotTXWSfjehTGRLgrtOnUOpZycJyqVbEahsOx5KJOwaq0pRZ_l7hOCwncJJ5rernutAjrzA",
  • "provider": "AAD"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success",
  • "Session":
    {
    }
}

Log off

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.

Authorizations:
path Parameters
contactId
required
integer <int32>

The contact identifier

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.0/contacts/{contactId}/authentication/logoff
https://example-host/v1.0/contacts/{contactId}/authentication/logoff

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success"
}

ContactSignInManagement

Retrieve contact sign-in state

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.

Authorizations:
path Parameters
contactId
required
integer <int32>

The contact identifier

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

get/v1.0/contacts/{contactId}/sign-in/status
https://example-host/v1.0/contacts/{contactId}/sign-in/status

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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":
    {
    }
}

Update contact second-factor settings

Updates contact second-factor settings for authentication. The contact needs to have sign-in enabled and password set.

Authorizations:
path Parameters
contactId
required
integer <int32>

The contact identifier.

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

Second factor payload

isSecondFactorEnabled
boolean Nullable
secondFactorTypeId
integer <int32> Nullable

Responses

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

patch/v1.1/contacts/{contactId}/sign-in/second-factor
https://example-host/v1.1/contacts/{contactId}/sign-in/second-factor

Request samples

Content type
Copy
Expand all Collapse all
{
  • "isSecondFactorEnabled": true,
  • "secondFactorTypeId": 0
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "code": "General",
  • "subCode": "string",
  • "message": "string",
  • "correlationId": "string",
  • "properties":
    {
    }
}

Enable contact sign-in.

Enables contact sign-in ability to DFS.

Authorizations:
path Parameters
contactId
required
integer <int32>

The ID of the contact to enable

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Responses

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.0/contacts/{contactId}/sign-in/enable
https://example-host/v1.0/contacts/{contactId}/sign-in/enable

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "code": "General",
  • "subCode": "string",
  • "message": "string",
  • "correlationId": "string",
  • "properties":
    {
    }
}

Enable contact sign-in through key validation.

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.

Authorizations:
path Parameters
key
required
string

The key of the contact to activate

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.0/contacts/sign-in/enable/{key}
https://example-host/v1.0/contacts/sign-in/enable/{key}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "contactId": 0,
  • "username": "string",
  • "isPasswordSet": true
}

Disable contact sign-in.

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.

Authorizations:
path Parameters
contactId
required
integer <int32>

The ID of the contact to deactivate

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Responses

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.0/contacts/{contactId}/sign-in/disable
https://example-host/v1.0/contacts/{contactId}/sign-in/disable

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "code": "General",
  • "subCode": "string",
  • "message": "string",
  • "correlationId": "string",
  • "properties":
    {
    }
}

Send key to enable contact sign-in.

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.

Authorizations:
path Parameters
contactId
required
integer <int32>
header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:
redirectUrl
string Nullable
channel
string (CommunicationChannel)
Enum: "Email" "Mobile"

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.0/contacts/{contactId}/sign-in/enable/send-key
https://example-host/v1.0/contacts/{contactId}/sign-in/enable/send-key

Request samples

Content type
Copy
Expand all Collapse all
{
  • "redirectUrl": "string",
  • "channel": "Email"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "GeneratedKey": "7B2C4E"
}

Unlock

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.

Authorizations:
path Parameters
contactId
required
integer <int32>

The contact identifier

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.0/contacts/{contactId}/sign-in/unlock
https://example-host/v1.0/contacts/{contactId}/sign-in/unlock

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success"
}

Futurae

Futurae success callback authenticate

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.

Authorizations:
query Parameters
authorization
string

The tenant hash identifier

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

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.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.1/callback/authentication/futurae
https://example-host/v1.1/callback/authentication/futurae

Request samples

Content type
Copy
Expand all Collapse all
{
  • "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"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success"
}

Futurae success callback enrollment

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.

Authorizations:
query Parameters
authorization
string

The tenant hash identifier

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

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.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.1/callback/enrollment/futurae
https://example-host/v1.1/callback/enrollment/futurae

Request samples

Content type
Copy
Expand all Collapse all
{
  • "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"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success"
}

PasswordManagement

Get password policies with the details

Returns the list of password policies with the details (including settings)

Authorizations:
header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

get/v1.0/authentication/password/policies
https://example-host/v1.0/authentication/password/policies

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Policies":
    [
    ]
}

Update contact password

Updates contact password given the old password. The new password is validated against the contact password policies.

Authorizations:
path Parameters
contactId
required
integer <int32>

The contact identifier

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

The update contact password request

oldPassword
string Nullable
newPassword
string Nullable

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

patch/v1.0/contacts/{contactId}/password
https://example-host/v1.0/contacts/{contactId}/password

Request samples

Content type
Copy
Expand all Collapse all
{
  • "oldPassword": "string",
  • "newPassword": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "ValidationResult":
    {
    },
  • "Result": "Success"
}

Trigger forgotten password flow

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.

Authorizations:
header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

The trigger forgotten password request

email
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.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.0/contacts/forgotten-password/send-preliminary-key
https://example-host/v1.0/contacts/forgotten-password/send-preliminary-key

Request samples

Content type
Copy
Expand all Collapse all
{
  • "email": "string",
  • "username": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "GeneratedSessionId": "string",
  • "GeneratedKey": "string"
}

Send reset-password key

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.

Authorizations:
header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

The send reset password key request

preliminaryKey
string Nullable
sessionId
string Nullable
redirectUrl
string Nullable

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.0/contacts/forgotten-password/send-reset-key
https://example-host/v1.0/contacts/forgotten-password/send-reset-key

Request samples

Content type
Copy
Expand all Collapse all
{
  • "preliminaryKey": "string",
  • "sessionId": "string",
  • "redirectUrl": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success",
  • "GeneratedKey": "string"
}

Reset contact password through key validation.

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.

Authorizations:
path Parameters
key
required
string

The key

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

The reset password request

password
string Nullable

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.0/contacts/reset-password/{key}
https://example-host/v1.0/contacts/reset-password/{key}

Request samples

Content type
Copy
Expand all Collapse all
{
  • "password": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "ValidationResult":
    {
    },
  • "Result": "Success"
}

Send reset-password key

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.

Authorizations:
path Parameters
contactId
required
integer <int32>

The contact identifier

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

The reset password request

redirectURL
string Nullable
channel
string (CommunicationChannel)
Enum: "Email" "Mobile"

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.0/contacts/{contactId}/reset-password/send-reset-key
https://example-host/v1.0/contacts/{contactId}/reset-password/send-reset-key

Request samples

Content type
Copy
Expand all Collapse all
{
  • "redirectURL": "string",
  • "channel": "Email"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "generatedKey": "string"
}

SecondFactorDeviceEnrollment

Retrieve contact’s enrolled devices

Retrieves contact’s enrolled devices used for second factor authentication.

Authorizations:
path Parameters
contactId
required
integer <int32>

The contact identifier for which the enrolled devices will be returned.

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

get/v1.0/contacts/{contactId}/enrolled-devices
https://example-host/v1.0/contacts/{contactId}/enrolled-devices

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Results":
    [
    ]
}

Enroll by contact id

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.

Authorizations:
path Parameters
contactId
required
integer <int32>

The contact identifier for which the device will be enrolled.

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.1/contacts/{contactId}/enrollment/enroll
https://example-host/v1.1/contacts/{contactId}/enrollment/enroll

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Enroll by user name

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.

Authorizations:
header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

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.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.1/enrollment/enroll
https://example-host/v1.1/enrollment/enroll

Request samples

Content type
Copy
Expand all Collapse all
{
  • "userName": "john.doe@additiv.com",
  • "password": "%DR@Ja+G)8cU3Fkr"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Enroll status

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.

Authorizations:
header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

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.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.1/enrollment/status
https://example-host/v1.1/enrollment/status

Request samples

Content type
Copy
Expand all Collapse all
{
  • "userName": "john.doe@additiv.com",
  • "enrollmentSessionId": "1ebbedb9987d4e189d837fad4114e7d0"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success",
  • "Status": "Pending"
}

Unenroll latest enrolled device

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

Authorizations:
path Parameters
contactId
required
integer <int32>

The contact identifier for which the enrolled device will be unenrolled.

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

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.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.1/contacts/{contactId}/enrollment/unenroll
https://example-host/v1.1/contacts/{contactId}/enrollment/unenroll

Request samples

Content type
Copy
Expand all Collapse all
{
  • "disableTwoFactor": true
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success"
}

TokenManagement

Get token by session id

Gets a JWT token for a given sessionId.

Authorizations:
path Parameters
contactId
required
integer <int32>

The ID of the contact that the token belongs to.

sessionId
required
string

The session identifier.

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

get/v1.1/contacts/{contactId}/authentication/tokens/{sessionId}
https://example-host/v1.1/contacts/{contactId}/authentication/tokens/{sessionId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success",
  • "Session":
    {
    }
}

Validate token

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).

Authorizations:
header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

The validate token request

accessToken
string Nullable

The JWT access token that will be validated.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

post/v1.0/authentication/tokens/validate
https://example-host/v1.0/authentication/tokens/validate

Request samples

Content type
Copy
Expand all Collapse all
{
  • "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI3NTIzMzE0YjU4ZDU0YTQxYTA1YzI2NDA4MmQzZDRlMiIsImlzcyI6IkFkZGl0aXYgQUciLCJzdWIiOiJzdGVsaWFuLmR1bWl0cmEiLCJpYXQiOjE1NDY4NTg4OTYsImV4cCI6MTU0Njg2MDA5NiwiY2lkIjoxMjM0LCJtaWQiOjB9.VA3Qlfs8tzqryo6imIyZ7vcRDipDI71W_7O6seuojhvoiWom8r0mQMIzgfzTB01CXFvBpx-BhfzODFT1bPsqSoSMdMEiwqMQA3TzaWDfkFmsfQ6ZEx9D7PbUD6TtHj8IrJFrIwlPBlRDuUXPz6lOxdaGMQxmpQagtLi-5NWmQPrj4WjmEvzDLcuWyjWZAuLqTr1xabVGYyZd-kb2dENaDdcjb73jsyw89ChnYii_5j81-mcudouwPIdm5ECvKBW5G2Anbi0ITwusS9eHGd7bx5JAJYKtpt8o2hk4VLC5qx4S6jCn0sTEiB5Kz5FxgFeAHfYesIPOY7SYTLPmF1A7Xw"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success"
}

Renew token

Renews an expired or existing session/JWT token. Returns the renewed JWT token along with session id.

Authorizations:
path Parameters
contactId
required
integer <int32>

The contact identifier

header Parameters
Accept-Language
string

The ISO 639-1 language to use for localizable data.

Request Body schema:

The renew token request

accessToken
string Nullable

The access token that will be renewed.

Responses

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

UnprocessableEntity

500

Internal Server Error

put/v1.0/contacts/{contactId}/authentication/tokens/renew
https://example-host/v1.0/contacts/{contactId}/authentication/tokens/renew

Request samples

Content type
Copy
Expand all Collapse all
{
  • "accessToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjUxMThGM0YxRkRDMDcyRjAwNjA2NzU5NjY3N0NEQTNFIiwidHlwIjoiYXQrand0In0.eyJuYmYiOjE2MTM1NTQwMzMsImV4cCI6MTYxMzU1NzYzMywiaXNzIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6NDQzNTIiLCJhdWQiOlsiSWRlbnRpdHlTZXJ2ZXJBcGkiLCJTZXJ2aWNlTGF5ZXJBcGkiLCJBZG1pblNlcnZpY2VBcGkiLCJEbXNTZXJ2aWNlQXBpIiwiQWxlcnRpbmdTZXJ2aWNlQXBpIiwiU3RhbmRhcmRUYXNrc0FwaSIsIkVuZ2FnZW1lbnRDb250ZW50QXBpIiwiTWlzU2VydmljZXNBcGkiLCJEeW5hbWljQ2xpZW50U2VydmljZXNBcGkiLCJBbGVydGluZ0xpc3RlbmVyQXBpIiwiVGFza0F1dG9tYXRpb25BcGkiXSwiY2xpZW50X2lkIjoiS3QyYWNBVTRFUEF0a1N3dEY0WVozYUNKNWZmREFIIiwiYWNpZCI6Ii0zIiwidHVpZCI6ImFmNGM3OWIyLTVlZGQtNGZiMi1iOWRmLTM1ODRhNTk0MWZlYiIsInRpZCI6IjIiLCJ0a3kiOiJBZGRpdGl2IiwianRpIjoiOURERjY3QzFGMEZBMDBBQkQzRDI3MjQ5REZFRjEzOTgiLCJpYXQiOjE2MTM1NTQwMzMsInNjb3BlIjpbImFwcF9pbXBlcnNvbmF0aW9uIiwiRGZzQXBpIl19.mIeMWRj0Kgj3op2462aLIw_5oBFZxU5GJAV1rTmZhq-2LrwagiqKGQ5bizGKRdW8DcGvLKtMxzfp3RxpqxT9yZyzO5SBxswxJAt1KW-LOQmIh60fCJUfKm53BkkhEgESAx8vplGdHqGzKx4St8YpTB7Wl8_-7QNvf8po5IBNKKCXnRGFLmiM2aNVSHZTc6hQB4phI5astDOIupZWYPrZkhNa6WP11fb9XEi2h7gVeVT_pSZbufckah8bRV0-YYo2kO9ZTDZJRCkZ3TPwNDW8CxvFQyUj2gP3lQiM1yYblMKSVDvIncrENw9A53hbCN9xcpEJhO2dfU3gtGHtx39dfg"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Result": "Success",
  • "Session":
    {
    }
}