API Reference

This document is meant to provide clear and comprehensive information and details about the API, especially each endpoint. If you are looking for a document to guide you through its usage, refer to the guide document.

Endpoint Details

User Management

GET - Get the current user data

Get the current user information.

Endpoint	/users/me
Protected	Yes
Parameters

Success

200

Errors

400	No more precision
401	No more precision

GET - Get user list

Endpoint	/users
Protected	Yes
Parameters	extended (boolean, optional) - The filter allows to fetch more data for each user

Success

200

Errors

400	No more precision
401	No more precision

POST - Add new user

Endpoint	/users
Protected	No
Parameters	fullname (string, required) - User full name email (string, required) - User email password (string, required) - User password mfaEnabled (boolean, required) - Whether to setup MFA along with user creation

Success

200
200

Errors

400	No more precision

DELETE - Delete user

Endpoint	/users/me
Protected	Yes
Parameters	id (string, required) - User public id

Success

204

Errors

400	No more precision
401	No more precision
404	No more precision

Authentication Management

There are 2 approaches for authentication, standard credentials authentication and with 2FA authentication.

Credentials

POST - Sign in and create a new JWT session

Endpoint	/auth/sessions
Protected	No
Parameters	username (string, required) - User email or any configured valid username password (string, required) - User password

Success

200

Errors

400	No more precision
401	No more precision
404	No more precision

Credentials (with 2FA)

Authenticating with 2FA is a 2 steps process. If you want more information about this topic, refers to the workflow reference.

1. Step1, is a "security challenge” step. When successful, provide the user with a mfaAccessToken
2. Step2, is a "identity challenge” step. When successful, provides the final accessToken JWT needed resource access operations

POST - Obtain mfaAccessToken with valid credentials (Step1)

Endpoint	/auth/sessions
Protected	No
Parameters	username (string, required) - User email or any configured valid username password (string, required) - User password

Success

200

Errors

400	No more precision
401	No more precision
404	No more precision

POST - Obtain final accessToken with valid mfaToken (Step2)

Endpoint	/auth/mfa/sessions
Protected	No
Parameters	mfaAccessToken (string, required) - `access token`` from step1 mfaMethod (string, required) - Valid MFA method mfaToken (string, required) - Valid MFA token (TOTP code, OTP code, backup code, …)

Success

200

Errors

400	No more precision
401	No more precision
404	No more precision

2FA token verification

POST - Verify a mfaToken

This endpoint is suitable to verify the identity of an user in a protected context.

Endpoint	/auth/mfa/verify
Protected	Yes
Parameters	mfaToken (string, required) - Valid MFA token (TOTP code, OTP code, backup code, …)

Success

204

Errors

400	> No more backup code available
401	> Invalid 2FA token or backup code

2FA Management

PUT - Setup MFA for the current user

Endpoint	/mfa
Protected	Yes
Parameters	mfaMethod (string, required) - Valid MFA method

Success

200

Errors

400	No more precision
401	No more precision
404	No more precision

PATCH - Enable / Disable MFA for the current user

Endpoint	/mfa
Protected	Yes
Parameters	mfaEnabled (boolean, required) - Whether to disable or enable mfaMethod (string, required) - Valid MFA method

Success

204

Errors

400	No more precision
401	No more precision
404	No more precision

DELETE - Reset MFA for the current user

Endpoint	/mfa
Protected	Yes
Parameters

Success

204

Errors

400	No more precision
401	No more precision
404	No more precision

Token Management

POST - Information about an access token

Endpoint	/token/introspect
Protected	Yes
Parameters	token (string, required) - Whether to disable or enable

Success

200

Errors

400	No more precision
401	No more precision
404	No more precision