# Auth controller (/auth)

This controller contains endpoints related to authentication: creating an account, logging in, and password management.

Endpoints in alphabetical order:

/auth/change-password (POST)
/auth/login (POST)
/auth/login-as (GET)
/auth/login-username (POST)
/auth/logout (GET)
/auth/mfa (DELETE)
/auth/mfa/add (POST)
/auth/mfa/add/totp/qrcode (GET)
/auth/mfa/add/verify (POST)
/auth/mfa/default (POST)
/auth/mfa/list (GET)
/auth/mfa/request-verify (GET)
/auth/mfa/verify (POST)
/auth/request-reset-password (GET)
/auth/request-verify-email (GET)
/auth/reset-password (POST)
/auth/signup (POST)
/auth/signup-temporary-user (POST)
/auth/verify-email (POST)

/auth/signup POST

Description

Creates a new SenSeeAct user. The user will have role patient and will be added to the specified project. An email will be sent to the user to confirm their email address.

Authorization

Any user can call this endpoint without authentication.

URL parameters

–

Content (application/json)

Email address of the new user. The email address is always stored in lower case.

password

Password of the new user

project

(optional) The project code to which the user should be added. If not specified, the user won’t be added to any project.

tokenExpiration

(optional) The number of minutes after which the token should expire, or “never”. If not specified, the token and cookie will expire after 1440 minutes (24 hours).
If “cookie” is true, then the cookie will also expire after this number of minutes. A cookie cannot be set to never expire. If you set this parameter to “never”, then the cookie will be set to expire after a year.

(optional) true if the response should set HttpOnly cookie “authToken”. The cookie will expire according to “tokenExpiration”. The default is false.

autoExtendCookie

(optional) If “cookie” is true and you set this parameter to true, then the cookie will be automatically extended at every call. This means that a new token is generated that expires according to “tokenExpiration”, that token is set again in HttpOnly cookie “authToken”, and the cookie expires according to “tokenExpiration”. The default is false.

emailTemplate

(optional) The name of a custom email template to use for the email with the confirmation link. These templates are defined in class EmailTemplateRepository.

Response (application/json)

A JSON object with the following properties:

user

User ID

token

Authentication token

Errors

If a user with the same email address already exists.

HTTP status

403 Forbidden

Code

USER_ALREADY_EXISTS

Field errors

Example

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/signup
Content-Type: application/json
 
{
    "email": "user@example.com",
    "password": "p4ssW0rd",
    "tokenExpiration": 1440,
    "project": "default",
    "cookie": false,
    "autoExtendCookie": false
}

Response

{
    "user": "7871f17faf4545389b53b55eea7fd991",
    "token": "eyJhbGci..."
}

/auth/signup-temporary-user POST

Description

Creates a new temporary SenSeeAct user. The user will have role patient and will be added to the specified project. This endpoint creates a user with a random email address in domain “temp.senseeact.com” and a random password. It will be automatically deleted after 24 hours.

The user can be made permanent by changing the email address (

PUT /user/

). In that case you probably want to change the password as well (

/auth/change-password

Authorization

Any user can call this endpoint without authentication.

URL parameters

–

Content (application/json)

project

(optional) The project code to which the user should be added. If not specified, the user won’t be added to any project.

tokenExpiration

(optional) true if the response should set HttpOnly cookie “authToken”. The cookie will expire according to “tokenExpiration”. The default is false.

autoExtendCookie

Response (application/json)

A JSON object with the following properties:

user

User ID

token

Authentication token

Example

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/signup-temporary-user
Content-Type: application/json
 
{
    "tokenExpiration": 1440,
    "project": "default",
    "cookie": false,
    "autoExtendCookie": false
}

Response

{
    "user": "7871f17faf4545389b53b55eea7fd991",
    "token": "eyJhbGci..."
}

/auth/login POST

Description

If the account has a verified multi-factor authentication record (see

/auth/mfa/list

), then this endpoint will return status REQUIRES_MFA. In that case you need to perform an additional authentication against an MFA record through a verification code. The default MFA record, included in the result of this endpoint, has automatically been triggered for the user to obtain the verification code. How this is done, depends on the MFA type:

TOTP: Nothing is done. The user can get a verification code any time from their authenticator app, such as Authy.
SMS: The verification code is sent by SMS to the phone number stored in the MFA record.

When you have the verification code, you should verify it with

/auth/mfa/verify

to complete the authentication.

Authorization

Any user can call this endpoint without authentication.

URL parameters

–

Content (application/json)

Email address of the user

password

Password of the user

tokenExpiration

(optional) true if the response should set HttpOnly cookie “authToken”. The cookie will expire according to “tokenExpiration”. The default is false.

autoExtendCookie

Response (application/json)

A JSON object with the following properties:

status

One of: COMPLETE, REQUIRES_MFA

user

User ID

Email address

token

Authentication token

mfaRecord

If the status is REQUIRES_MFA, then this is the default MFA record that has been triggered for the user to obtain a verification code. See

/auth/mfa/list

for the format.

Errors

If the email address or password is incorrect. It will not tell which is incorrect to prevent guessing for existing email addresses.

HTTP status

401 Unauthorized

Code

INVALID_CREDENTIALS

Field errors

–

If the account for the specified email address has been deactivated.

HTTP status

401 Unauthorized

Code

ACCOUNT_INACTIVE

Field errors

–

If the account for the specified email address is temporarily blocked because of too many failed login attempts.

HTTP status

401 Unauthorized

Code

ACCOUNT_BLOCKED

Field errors

–

Example

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/login
Content-Type: application/json
 
{
    "email":"user@example.com",
    "password":"p4ssW0rd",
    "tokenExpiration":1440,
    "cookie":false,
    "autoExtendCookie":false
}

Response (without MFA)

{
    "status": "COMPLETE",
    "user": "7871f17faf4545389b53b55eea7fd991",
    "email": "user@example.com",
    "token": "eyJhbGci..."
}

Response (with MFA)

{
    "status": "REQUIRES_MFA",
    "user": "7871f17faf4545389b53b55eea7fd991",
    "email": "user@example.com",
    "token": "eyJhbGci...",
    "mfaRecord": {
        "id": "16de88e0d0bd43f18742a83fe027d842"
        "type": "totp",
        "created": "2024-09-20T10:00:00.000Z",
        "verified": true,
        "data": {}
    }
}

/auth/login-username POST

Description

Unlike

/auth/login

you may log in using only the local part of the email address for some domains that are linked to a project. If the local part is unique across the supported domains, it will be equivalent to providing the complete email address.

For example user ‘myappuser01@myapp.example.com’ could also log in with just ‘myappuser01’.

If the account has a verified multi-factor authentication record (see

/auth/mfa/list

TOTP: Nothing is done. The user can get a verification code any time from their authenticator app, such as Authy.
SMS: The verification code is sent by SMS to the phone number stored in the MFA record.

When you have the verification code, you should verify it with

/auth/mfa/verify

to complete the authentication.

Authorization

Any user can call this endpoint without authentication.

URL parameters

–

Content (application/json)

username

Email address or user name of the user

password

Password of the user

tokenExpiration

(optional) true if the response should set HttpOnly cookie “authToken”. The cookie will expire according to “tokenExpiration”. The default is false.

autoExtendCookie

Response (application/json)

A JSON object with the following properties:

status

One of: COMPLETE, REQUIRES_MFA

user

User ID

Email address

token

Authentication token

mfaRecord

If the status is REQUIRES_MFA, then this is the default MFA record that has been triggered for the user to obtain a verification code. See

/auth/mfa/list

for the format.

Errors

If the email address or password is incorrect, or if there are more users with the same user name in other supported domains. It will not tell which is incorrect to prevent guessing for existing email addresses or user names.

HTTP status

401 Unauthorized

Code

INVALID_CREDENTIALS

Field errors

–

If the account for the specified user has been deactivated.

HTTP status

401 Unauthorized

Code

ACCOUNT_INACTIVE

Field errors

–

If the account for the specified user is temporarily blocked because of too many failed login attempts.

HTTP status

401 Unauthorized

Code

ACCOUNT_BLOCKED

Field errors

–

Example

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/login-username
Content-Type: application/json
 
{
    "username": "user@example.com",
    "password": "p4ssW0rd",
    "tokenExpiration": 1440,
    "cookie": false,
    "autoExtendCookie": false
}

Response (without MFA)

{
    "status": "COMPLETE",
    "user": "7871f17faf4545389b53b55eea7fd991",
    "email": "user@example.com",
    "token": "eyJhbGci..."
}

Response (with MFA)

{
    "status": "REQUIRES_MFA",
    "user": "7871f17faf4545389b53b55eea7fd991",
    "email": "user@example.com",
    "token": "eyJhbGci...",
    "mfaRecord": {
        "id": "16de88e0d0bd43f18742a83fe027d842"
        "type": "totp",
        "created": "2024-09-20T10:00:00.000Z",
        "verified": true,
        "data": {}
    }
}

/auth/login-as GET

Description

Authorization

Only admins can call this endpoint. You cannot use this endpoint to log in as yourself and you cannot log in as an inactive user.

URL parameters

user

Email address of the user as whom you want to log in

Content

–

Response (application/json)

A JSON object with the following properties:

user

User ID

token

Authentication token

Errors

If the account for the specified user has been deactivated.

HTTP status

403 Forbidden

Code

ACCOUNT_INACTIVE

Field errors

–

Example

Request

GET https://www.example.com/servlets/senseeact/v6.1.0/auth/login-as?user=user@example.com
X-Auth-Token: ...

Response

{
    "user": "b43f784d76c44e7a9ae0370b91521753",
    "token": "eyJhbGci..."
}

# /logout

/auth/logout GET

Description

Logs out. The only effect of this endpoint is that the HttpOnly cookie “authToken” is cleared. If you have not requested that cookie at login, then this endpoint is not needed.

Authorization

Any user can call this endpoint without authentication.

URL parameters

–

Content

–

Response

–

Example

Request

GET https://www.example.com/servlets/senseeact/v6.1.0/auth/logout

Response

–

# /change-password

/auth/change-password POST

Description

Change the password of yourself or another user (admins only).

Authorization

All authenticated users can change their own password.
Admins can change the password of any user.

URL parameters

–

Content (application/json)

(optional) Email address of the user whose password should be changed. You can specify either “user” or “email”, or you can specify neither to change your own password.

user

(optional) User ID of the user whose password should be changed. You can specify either “user” or “email”, or you can specify neither to change your own password.

oldPassword

Old password. This is ignored if you are an admin or if you still have a temporary password (

/auth/signup-temporary-user

). Otherwise it is required.

newPassword

New password

tokenExpiration

(optional) true if the response should set HttpOnly cookie “authToken”. The cookie will expire according to “tokenExpiration”. The default is false.

autoExtendCookie

Response (string)

Authentication token

Example

Request (by user ID)

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/change-password
X-Auth-Token: ...
Content-Type: application/json
 
{
    "user": "b43f784d76c44e7a9ae0370b91521753",
    "oldPassword": "0ldP4ssW0rd",
    "newPassword": "n3wP4ssW0rd",
    "tokenExpiration": 1440,
    "cookie": false,
    "autoExtendCookie": false
}

Request (by email)

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/change-password
X-Auth-Token: ...
Content-Type: application/json
 
{
    "email": "user@example.com",
    "oldPassword": "0ldP4ssW0rd",
    "newPassword": "n3wP4ssW0rd",
    "tokenExpiration": 1440,
    "cookie": false,
    "autoExtendCookie": false
}

Response

eyJhbGci...

# /request-reset-password

/auth/request-reset-password GET

Description

Sends a request to reset the password for a user. An email with a reset link will be sent to the email address of the user.

You can use the HTTP header Accept-Language to specify a preferred language for the email. The default is English.

The email will contain a reset link with a code. This code can be used to reset the password with

/auth/reset-password

. The code will be valid for 24 hours.

Authorization

Any user can call this endpoint without authentication.

URL parameters

Email address of the user whose password should be reset

template

(optional) The name of a custom email template to use. These templates are defined in class EmailTemplateRepository.

Content

–

Response

–

Example

Request

GET https://www.example.com/servlets/senseeact/v6.1.0/auth/request-reset-password
    ?email=user@example.com
Accept-Language: nl-NL,nl;q=0.9,*;q=0.1

Response

–

# /reset-password

/auth/reset-password POST

Description

Resets the password of a user. You should specify the code that was received in the email from

/auth/request-reset-password

If the specified reset code is incorrect or expired, you have to call

/auth/request-reset-password

again. Any correct code is invalidated. Once the password has been reset, you cannot use the code again.

Authorization

Any user can call this endpoint without authentication.

URL parameters

–

Content (application/x-www-form-urlencoded)

Email address of the user whose password should be reset

code

Reset code received through email

password

New password

Response

–

Errors

If the reset code is not valid or no longer valid.

HTTP status

400 Bad Request

Code

INVALID_INPUT

Field errors

code

Example

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/reset-password
Content-Type: application/x-www-form-urlencoded
 
email=user@example.com&code=4428bb3891eb4ebe897bc1e68636e81d&password=p4ssW0rd

Response

–

# /request-verify-email

/auth/request-verify-email GET

Description

Sends the same email that is sent when a user signs up with

/auth/signup

. The email contains a link that a user can open to confirm their email address.

You can use the HTTP header Accept-Language to specify a preferred language for the email. The default is English.

The email will contain a verification link with a code. This code can be used to confirm the email address with

/auth/verify-email

. The code will be valid for 24 hours.

Authorization

All authenticated users can request a verification email for themselves.

URL parameters

template

(optional) The name of a custom email template to use. These templates are defined in class EmailTemplateRepository.

Content

–

Response

–

Example

Request

GET https://www.example.com/servlets/senseeact/v6.1.0/auth/request-verify-email
    ?template=mytemplate
Accept-Language: nl-NL,nl;q=0.9,*;q=0.1

Response

–

# /verify-email

/auth/verify-email POST

Description

Confirms the email address of the user. You should specify the code that was received in the email from

/auth/request-verify-email

If the specified code is incorrect or expired, you have to call

/auth/request-verify-email

again. Any correct code is invalidated.

Authorization

Any user can call this endpoint without authentication.

URL parameters

–

Content (application/x-www-form-urlencoded)

user

User ID

code

Verification code received through email

Response

–

Errors

If the verification code is not valid or no longer valid.

HTTP status

400 Bad Request

Code

INVALID_INPUT

Field errors

code

Example

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/verify-email
Content-Type: application/x-www-form-urlencoded
 
user=7871f17faf4545389b53b55eea7fd991
&code=4428bb3891eb4ebe897bc1e68636e81d

Response

–

# /mfa/add

/auth/mfa/add POST

Description

Adds a multi-factor authentication record to the current user. As long as the account has a verified MFA record (see

/auth/mfa/list

TOTP (Time-based One-Time Password): The user retrieves a verification code from an authenticator app such as Authy.
SMS: The user receives a verification code in an SMS message sent to the phone number in the MFA record.

This endpoint returns an unverified MFA record, which should be verified with a verification code using

/auth/mfa/add/verify

. It depends on the MFA type how the code is obtained:

TOTP: The user should scan a QR code in their authenticator app. The QR code encodes the binding URI that is returned by this endpoint. The QR code image can be obtained with
/auth/mfa/add/totp/qrcode
. After scanning the code, the authenticator app will produce the verification code.
SMS: The verification code is sent by SMS to the phone number in the MFA record.

Authorization

Any authenticated user can call this endpoint.

URL parameters

type

One of: totp, sms

Content (application/json)

If the type is “totp”, the content can be empty.

If the type is “sms”, the content should be a JSON object with the following property:

phoneNumber

The phone number formatted as a plus sign followed by numbers: +00000000

Response (application/json)

The unverified MFA record as a JSON object with the following properties:

MFA record ID

type

One of: totp, sms

created

The system time when this record was created. This is an ISO date/time with a time zone: 2024-09-20T10:00:00.000Z

verified

Here it is always false.

data

A JSON object with the data associated with this record. This depends on the type as described below.
Note that this is the data of an unverified record. It contains more sensitive data than a verified record. An unverified record is only returned by this endpoint after complete authentication, whereas a verified record can be obtained after password authentication but before multi-factor authentication.

Data for TOTP record:

bindingUri

The binding URI that should be registered in the authenticator app. This is done by scanning the QR code for this URI. The QR code image can be obtained with

/auth/mfa/add/totp/qrcode

Data for SMS record:

phoneNumber

The phone number formatted as a plus sign followed by numbers: +00000000

Errors

If you have reached the maximum number of MFA records for the specified type (1 TOTP record, 2 SMS records).

HTTP status

400 Bad Request

Code

AUTH_MFA_TYPE_MAX

Field errors

type

If you have reached the maximum number of attempts to add an MFA record: 10 in 60 minutes.

HTTP status

400 Bad Request

Code

AUTH_MFA_ADD_MAX

Field errors

–

If you are adding an SMS record with a phone number for which a record already exists.

HTTP status

400 Bad Request

Code

AUTH_MFA_SMS_ALREADY_EXISTS

Field errors

phoneNumber

Example

Request (TOTP)

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/mfa/add
    ?type=totp
X-Auth-Token: ...

Response (TOTP)

{
    "id": "16de88e0d0bd43f18742a83fe027d842"
    "type": "totp",
    "created": "2024-09-20T10:00:00.000Z",
    "verified": false,
    "data": {
        "bindingUri": "otpauth://totp/SenSeeAct:user@example.com?..."
    }
}

Request (SMS)

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/mfa/add
    ?type=sms
X-Auth-Token: ...
 
{
    "phoneNumber": "+00000000"
}

Response (SMS)

{
    "id": "16de88e0d0bd43f18742a83fe027d842"
    "type": "sms",
    "created": "2024-09-20T10:00:00.000Z",
    "verified": false,
    "data": {
        "phoneNumber": "+00000000"
    }
}

# /mfa/add/totp/qrcode

/auth/mfa/add/totp/qrcode GET

Description

Returns the QR code image for the binding URI of a new multi-factor authentication record with type “totp”. This endpoint can be called after

/auth/mfa/add

The QR code should be scanned in an authenticator app, such as Authy. The authenticator app will show a verification code that can be passed to

/auth/mfa/add/verify

to complete the verification of the new MFA record.

Authorization

Any authenticated user can call this endpoint.

URL parameters

ID of the MFA record

Content

–

Response (image/png)

The QR code image.

Example

Request

GET https://www.example.com/servlets/senseeact/v6.1.0/auth/mfa/add/totp/qrcode
    ?id=16de88e0d0bd43f18742a83fe027d842
X-Auth-Token: ...

Response

<QR code image>

# /mfa/add/verify

/auth/mfa/add/verify POST

Description

Verifies a new multi-factor authentication record that was added with

/auth/mfa/add

. This endpoint needs a verification code. It depends on the MFA type how this code is obtained:

TOTP: The user should scan a QR code in their authenticator app. The QR code image can be obtained with
/auth/mfa/add/totp/qrcode
. After scanning the code, the authenticator app will produce the verification code.
SMS: The verification code is sent by SMS to the phone number in the MFA record.

If the specified verification code is correct, the record will be stored in the account of the current user as a verified MFA record. This endpoint returns the verified record, and an updated authentication token containing a reference to the new MFA record. If this is the first MFA record, then the previous token will no longer be valid, because it does not hold a now required MFA. If you are using the token cookie, then the cookie will be updated.

As long as the account has a verified MFA record (see

/auth/mfa/list

/auth/mfa/request-verify

Authorization

Any authenticated user can call this endpoint.

URL parameters

–

Content (application/json)

mfaId

ID of the MFA record

code

The verification code

Response (application/json)

A JSON object with the following properties:

mfaRecord

The verified MFA record (described below).

token

The updated authentication token.

The MFA record is a JSON object with the following properties:

MFA record ID

type

One of: totp, sms

created

The system time when this record was created. This is an ISO date/time with a time zone: 2024-09-20T10:00:00.000Z

verified

Here it is always true.

data

A JSON object with the data associated with this record. This depends on the type as described below.
Note that this is the data of a verified record. It contains less sensitive data than an unverified record. An unverified record is only returned by

/auth/mfa/add

after complete authentication, whereas a verified record can be obtained after password authentication but before multi-factor authentication.

Data for TOTP record:
Empty object.

Data for SMS record:

partialPhoneNumber

The phone number formatted as a plus sign followed by numbers. Only the first and last two numbers are shown. The rest is obscured with *. Example: +00****00.

Errors

If you have reached the maximum number of MFA records for the specified type (1 TOTP record, 2 SMS records).

HTTP status

400 Bad Request

Code

AUTH_MFA_TYPE_MAX

Field errors

type

If you have reached the maximum number of MFA verification attempts: 10 in 15 minutes.

HTTP status

400 Bad Request

Code

AUTH_MFA_VERIFY_MAX

Field errors

–

If you are adding an SMS record with a phone number for which a record already exists.

HTTP status

400 Bad Request

Code

AUTH_MFA_SMS_ALREADY_EXISTS

Field errors

phoneNumber

Example

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/mfa/add/verify
X-Auth-Token: ...
 
{
    "mfaId": "16de88e0d0bd43f18742a83fe027d842",
    "code": "123456"
}

Response (TOTP)

{
    "mfaRecord": {
        "id": "16de88e0d0bd43f18742a83fe027d842"
        "type": "totp",
        "created": "2024-09-20T10:00:00.000Z",
        "verified": true,
        "data": {}
    },
    "token": "eyJhbGci..."
}

Response (SMS)

{
    "mfaRecord": {
        "id": "16de88e0d0bd43f18742a83fe027d842"
        "type": "sms",
        "created": "2024-09-20T10:00:00.000Z",
        "verified": true,
        "data": {
            "partialPhoneNumber": "+00****00"
        }
    },
    "token": "eyJhbGci..."
}

# /mfa (DELETE)

/auth/mfa DELETE

Description

Deletes a multi-factor authentication record from the account of the current user. If there are no remaining MFA records after this, then new logins no longer require MFA.

Authorization

Any authenticated user can call this endpoint.

URL parameters

ID of the MFA record

Content

–

Response

–

Example

Request

DELETE https://www.example.com/servlets/senseeact/v6.1.0/auth/mfa
    ?id=16de88e0d0bd43f18742a83fe027d842
X-Auth-Token: ...

Response

–

# /mfa/list

/auth/mfa/list GET

Description

Returns a list of all verified multi-factor authentication records for the current user. There are two supported types of MFA:

TOTP (Time-based One-Time Password): The user retrieves a verification code from an authenticator app such as Authy.
SMS: The user receives a verification code in an SMS message sent to the phone number in the MFA record.

As long as the account has a verified MFA record, every login requires an additional authentication against an MFA record through a verification code. The first MFA record is the default. This means that a login automatically triggers that record for the user to obtain the verification code. See also

/auth/mfa/request-verify

Authorization

Any user that has authenticated with their password can call this endpoint, even if they have not completed multi-factor authentication.

URL parameters

–

Content

–

Response (application/json)

JSON list with MFA records. Each record is a JSON object with the following properties:

MFA record ID

type

One of: totp, sms

created

The system time when this record was created. This is an ISO date/time with a time zone: 2024-09-20T10:00:00.000Z

verified

Here it is always true.

data

/auth/mfa/add

after complete authentication, whereas a verified record can be obtained after password authentication but before multi-factor authentication.

Data for TOTP record:
Empty object.

Data for SMS record:

partialPhoneNumber

The phone number formatted as a plus sign followed by numbers. Only the first and last two numbers are shown. The rest is obscured with *. Example: +00****00.

Example

Request

GET https://www.example.com/servlets/senseeact/v6.1.0/auth/mfa/list
X-Auth-Token: ...

Response

[
    {
        "id": "16de88e0d0bd43f18742a83fe027d842"
        "type": "totp",
        "created": "2024-09-20T10:00:00.000Z",
        "verified": true,
        "data": {}
    },
    {
        "id": "16de88e0d0bd43f18742a83fe027d842"
        "type": "sms",
        "created": "2024-09-20T10:00:00.000Z",
        "verified": true,
        "data": {
            "partialPhoneNumber": "+00****00"
        }
    }
]

# /mfa/default

/auth/mfa/default POST

Description

Sets the default multi-factor authentication record for the current user. The specified MFA record will be moved to the front of the list as returned by

/auth/mfa/list

. A login automatically triggers the default record for the user to obtain the verification code. See also

/auth/mfa/request-verify

Authorization

Any authenticated user can call this endpoint.

URL parameters

ID of the MFA record

Content

–

Response

–

Example

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/mfa/default
    ?id=16de88e0d0bd43f18742a83fe027d842
X-Auth-Token: ...

Response

–

# /mfa/request-verify

/auth/mfa/request-verify GET

Description

Starts a multi-factor authentication against the specified MFA record in the account of the current user. Depending on the MFA type, as described below, this method can be called for the user to obtain a verification code, which can be verified with

/auth/mfa/verify

As long as the account has a verified MFA record (see

/auth/mfa/list

), every login requires an additional authentication against an MFA record through a verification code. The first MFA record is the default. This means that a login automatically triggers that record for the user to obtain the verification code. In that case you should not call this endpoint as well. You can call this endpoint if the user needs to obtain the verification code again, or to authenticate against a different MFA record.

What this method does, depends on the MFA type.

TOTP: Nothing is done. The user can get a verification code any time from their authenticator app, such as Authy.
SMS: The verification code is sent by SMS to the phone number stored in the MFA record.

Authorization

Any user that has authenticated with their password can call this endpoint, even if they have not completed multi-factor authentication.

URL parameters

ID of the MFA record

Content

–

Response

–

Example

Request

GET https://www.example.com/servlets/senseeact/v6.1.0/auth/mfa/request-verify
    ?id=16de88e0d0bd43f18742a83fe027d842
X-Auth-Token: ...

Response

–

# /mfa/verify

/auth/mfa/verify POST

Description

Verifies a multi-factor authentication code against the specified MFA record for the current user. Usually you call this method when a call of

/auth/login

resulted in status REQUIRES_MFA. This means that the user authenticated with their password, but their account has a verified MFA record, so multi-factor authentication is required. The first MFA record (see

/auth/mfa/list

) is the default. The login automatically triggered that record for the user to obtain the verification code.

See

/auth/mfa/request-verify

for more information on how to obtain the verification code.

This method effectively completes the authentication and returns a result with a token, just like

/auth/login

Authorization

Any user that has authenticated with their password can call this endpoint, even if they have not completed multi-factor authentication.

URL parameters

–

Content (application/json)

mfaId

ID of the MFA record

code

The verification code

Response (application/json)

A JSON object with the following properties:

status

Here it is always “COMPLETE”.

user

User ID

Email address

token

Authentication token

Errors

If you have reached the maximum number of MFA verification attempts: 10 in 15 minutes.

HTTP status

400 Bad Request

Code

AUTH_MFA_VERIFY_MAX

Field errors

–

Example

Request

POST https://www.example.com/servlets/senseeact/v6.1.0/auth/mfa/verify
X-Auth-Token: ...
 
{
    "mfaId": "16de88e0d0bd43f18742a83fe027d842",
    "code": "123456"
}

Response

{
    "status": "COMPLETE",
    "user": "7871f17faf4545389b53b55eea7fd991",
    "email": "user@example.com",
    "token": "eyJhbGci..."
}

← SenSeeAct API /user →

# Auth controller (/auth)

# /signup

# /signup-temporary-user

# /login

# /login-username

# /login-as

# /logout

# /change-password

# /request-reset-password

# /reset-password

# /request-verify-email

# /verify-email

# /mfa/add

# /mfa/add/totp/qrcode

# /mfa/add/verify

# /mfa (DELETE)

# /mfa/list

# /mfa/default

# /mfa/request-verify

# /mfa/verify