MFT API - Authentication & Authorization 3.11.1

This API scope covers all operations related to user authentication, single sign-on (SSO), multi-factor authentication (MFA), Windows authentication, token management, and authorization checks within the MFT system.

The base endpoint URL for all operations in this scope is http://localhost:8010/vault_rest.

Authentication Requirements: Most endpoints in this scope require authentication.

Basic Authentication: Used for initial login/authentication endpoints (e.g., /vault_rest/authenticate). Provide username and password in the Authorization header using Basic scheme.
Bearer Token Authentication: Used for all other authenticated endpoints. After successful authentication, an API key (token) is issued. This token must be included in the Authorization header of subsequent requests using the Bearer scheme (e.g., Authorization: Bearer <your_api_key>).

Usage Notes:

The /vault_rest/authenticate endpoint is typically used to obtain an initial API key.
Token management endpoints allow for extending, creating, deleting, and recycling API keys.
SSO and MFA endpoints provide mechanisms for integrating with external identity providers and enforcing multi-factor authentication policies.
The /vault_rest/authenticate-windows endpoint facilitates Windows-integrated authentication, leveraging existing Windows session credentials.

Server

http://localhost:8010

Authentication

http bearerAuth

Bearer token obtained after successful authentication. Example: Authorization: Bearer <your_api_key>

http basicAuth

Basic authentication using username and password. Example: Authorization: Basic <base64_encoded_username:password>

Authentication

Endpoints for user login, logout, and general authentication processes.

GET

/vault_rest/authenticate

DELETE

/vault_rest/authenticate

Request an API Key

Authenticates a user and requests a new API key (token). This endpoint typically requires Basic Authentication (username and password) in the Authorization header. Upon successful authentication, a bearer token is returned, which should be used for subsequent API calls.

Since ## 3.11.1

Auth

GET /vault_rest/authenticate

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/authenticate' \ --header 'Authorization: Basic {token}'
Copy

Responses

200

Authentication successful, API key returned.

object	object
Result	string	The result of the authentication attempt. Enum: `Success`,`ErrorServiceUnavailable`,`ErrorInvalidCredentials`,`ErrorMfaRequired`
Token	string	The authentication token (API key) if authentication was successful.
Expires	date-time	The expiration date and time of the token.
ExpiresString	string	The expiration date and time of the token as a string.
UiMessageKey	string	A key for a UI message related to the authentication result.
Message	string	A detailed message related to the authentication result.

Response

xxxxxxxxxx
 
{ "Result": "Success", "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "Expires": "2024-12-31T23:59:59.000Z", "ExpiresString": "2024-12-31T23:59:59.000Z", "UiMessageKey": "LOGIN_SUCCESS", "Message": "User authenticated successfully."}
Copy

Log Out and Invalidate API Key

Logs out the current user by invalidating their active API key (token). This action effectively ends the current session.

Since ## 3.11.1

Auth

DELETE /vault_rest/authenticate

xxxxxxxxxx
 
curl --request DELETE \ --url 'http://localhost:8010/vault_rest/authenticate' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

API key invalidated successfully.

object object

Result

string

The result of the token cancellation.

Enum: Success,Error

Response

xxxxxxxxxx
 
{ "Result": "Success"}
Copy

Sso

Endpoints for Single Sign-On (SSO) integration and authentication flows.

GET

/vault_rest/pre-authenticate-sso

GET

/vault_rest/authenticate-sso

POST

/vault_rest/authenticate-sso

GET

/vault_rest/authenticate-sso-token

Initiate SSO Pre-authentication

Initiates the Single Sign-On (SSO) pre-authentication process. This endpoint is typically the first step in an SSO flow, preparing the system for an external identity provider redirect.

Since ## 3.11.1

Auth

GET /vault_rest/pre-authenticate-sso

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/pre-authenticate-sso' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

SSO pre-authentication initiated successfully.

object	object
redirectUrl	string	The URL to redirect the user to for SSO authentication.
state	string	A state parameter to maintain state between the request and the callback.

Response

xxxxxxxxxx
 
{ "redirectUrl": "https://idp.example.com/oauth2/authorize?client_id=...&response_type=code&scope=openid&redirect_uri=...&state=...", "state": "random_state_string"}
Copy

Complete SSO Authentication (GET)

Completes the Single Sign-On (SSO) authentication process using a GET request, typically after a redirect from an identity provider. The code and state parameters are crucial for validating the authentication flow.

Since ## 3.11.1

Auth

Query String

code	string	The authorization code received from the identity provider.
state	string	The state parameter used to prevent CSRF attacks, matching the one sent in the initial request.

GET /vault_rest/authenticate-sso

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/authenticate-sso' \ --header 'Authorization: Basic {token}' \ --data code={code} \ --data state={state}
Copy

Responses

200

SSO authentication completed successfully.

No response body

Response

xxxxxxxxxx
 
No response
Copy

Complete SSO Authentication (POST)

Completes the Single Sign-On (SSO) authentication process using a POST request. This endpoint is typically used by the SSO provider to send authentication data back to the MFT system.

Since ## 3.11.1

Auth

Request Body

SSO authentication content from the identity provider.

object object

POST /vault_rest/authenticate-sso

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/authenticate-sso' \ --header 'Authorization: Basic {token}' \ --data '{}'
Copy

Responses

200

SSO authentication completed successfully.

No response body

Response

xxxxxxxxxx
 
No response
Copy

Authenticate with SSO Token

Authenticates a user using an existing SSO token. This endpoint is used to validate and potentially refresh an SSO session.

Since ## 3.11.1

Auth

GET /vault_rest/authenticate-sso-token

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/authenticate-sso-token' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

SSO token authentication successful.

No response body

Response

xxxxxxxxxx
 
No response
Copy

Mfa

Endpoints for Multi-Factor Authentication (MFA) management and validation.

POST

/vault_rest/validate-otp

GET

/vault_rest/settings/mfa

POST

/vault_rest/settings/mfa

Validate One-Time Password (OTP)

Validates a One-Time Password (OTP) provided by the user, typically as part of a Multi-Factor Authentication (MFA) flow. The request body should contain the OTP.

Since ## 3.11.1

Auth

Request Body

OTP validation request body.

object object

POST /vault_rest/validate-otp

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/validate-otp' \ --header 'Authorization: Bearer {token}' \ --data '{}'
Copy

Responses

200

OTP validated successfully.

object object

Result

string

The result of the OTP validation.

Enum: Success,InvalidOtp,OtpExpired,Error

Token

string

The authentication token if OTP validation was successful and a new token is issued.

Response

xxxxxxxxxx
 
{ "Result": "Success", "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
Copy

Get MFA Settings

Retrieves the current Multi-Factor Authentication (MFA) settings for the system.

Since ## 3.11.1

Auth

GET /vault_rest/settings/mfa

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/settings/mfa' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

MFA settings retrieved successfully.

object object

MfaEnabled

boolean

Indicates if MFA is currently enabled.

MfaType

string

The type of MFA configured.

Enum: None,TOTP,SMS

Response

xxxxxxxxxx
 
{ "MfaEnabled": true, "MfaType": "TOTP"}
Copy

Update MFA Settings

Updates the Multi-Factor Authentication (MFA) settings for the system or a specific user. The request body contains the new MFA configuration.

Since ## 3.11.1

Auth

Request Body

MFA settings update request body.

object object

POST /vault_rest/settings/mfa

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/settings/mfa' \ --header 'Authorization: Bearer {token}' \ --data '{}'
Copy

Responses

200

MFA settings updated successfully.

object object

Result

string

The result of updating MFA settings.

Enum: Success,Error

Response

xxxxxxxxxx
 
{ "Result": "Success"}
Copy

Tokens

Endpoints for managing authentication tokens, including creation, extension, and deletion.

POST

/vault_rest/pre-exchange-token

POST

/vault_rest/exchange-token

/vault_rest/token/extend_session

GET

/vault_rest/tokens/generate

GET

/vault_rest/tokens/{start}/{count}

POST

/vault_rest/token/recycle

Initiate Token Exchange Pre-check

Initiates a pre-check for token exchange, often used in scenarios involving MFA or other conditional token issuance. This step might return information needed for the subsequent token exchange.

Since ## 3.11.1

Auth

Request Body

Pre-exchange token request body.

object object

POST /vault_rest/pre-exchange-token

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/pre-exchange-token' \ --header 'Authorization: Bearer {token}' \ --data '{}'
Copy

Responses

200

Token exchange pre-check successful.

object	object
challenge	string	A challenge string or identifier for the OTP exchange.

Response

xxxxxxxxxx
 
{ "challenge": "otp_challenge_123"}
Copy

Exchange Token

Exchanges a pre-authentication token or other credentials for a full API key. This is typically the final step in a multi-stage authentication process, such as after MFA validation.

Since ## 3.11.1

Auth

Request Body

Token exchange request body.

object object

POST /vault_rest/exchange-token

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/exchange-token' \ --header 'Authorization: Bearer {token}' \ --data '{}'
Copy

Responses

200

Token exchange successful, new API key issued.

object object

Result

string

The result of the token exchange.

Enum: Success,Error

Token

string

The new authentication token issued after exchange.

Response

xxxxxxxxxx
 
{ "Result": "Success", "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
Copy

Extend Authentication Token

Extends the expiration time of an existing authentication token. This allows users to maintain their session without re-authenticating.

Since ## 3.11.1

Auth

Request Body

Request body for extending the token.

object object

PUT /vault_rest/token

xxxxxxxxxx
 
curl --request PUT \ --url 'http://localhost:8010/vault_rest/token' \ --header 'Authorization: Bearer {token}' \ --data '{}'
Copy

Responses

200

Token extended successfully.

object object

Result

string

The result of extending the token.

Enum: Success,Error

NewExpires

date-time

The new expiration date and time of the token.

Response

xxxxxxxxxx
 
{ "Result": "Success", "NewExpires": "2025-01-01T00:00:00.000Z"}
Copy

Create Authentication Token

Creates a new authentication token. This endpoint might be used for generating API keys for programmatic access or for specific session types.

Since ## 3.11.1

Auth

Request Body

Request body for creating a new token.

object object

POST /vault_rest/token

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/token' \ --header 'Authorization: Bearer {token}' \ --data '{}'
Copy

Responses

200

New token created successfully.

object object

Result

string

The result of creating the token.

Enum: Success,Error

Token

string

The newly created authentication token.

Response

xxxxxxxxxx
 
{ "Result": "Success", "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
Copy

Delete Authentication Token

Deletes a specific authentication token, effectively logging out the associated session. The request body should specify which token to delete.

Since ## 3.11.1

Auth

Request Body

Request body for deleting the token.

object object

DELETE /vault_rest/token

xxxxxxxxxx
 
curl --request DELETE \ --url 'http://localhost:8010/vault_rest/token' \ --header 'Authorization: Bearer {token}' \ --data '{}'
Copy

Responses

200

Token deleted successfully.

object object

Result

string

The result of deleting the token.

Enum: Success,Error

Response

xxxxxxxxxx
 
{ "Result": "Success"}
Copy

Extend Idle Session

Extends the idle timeout for the current user session. This is typically called periodically by the client to keep the session alive.

Since ## 3.11.1

Auth

GET /vault_rest/token/extend_session

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/token/extend_session' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Idle session extended successfully.

object object

Result

string

The result of extending the idle session.

Enum: Success,Error

Response

xxxxxxxxxx
 
{ "Result": "Success"}
Copy

Generate a New Authentication Token

Generates a new, unique authentication token. This is often used for creating API keys for specific purposes or integrations.

Since ## 3.11.1

Auth

GET /vault_rest/tokens/generate

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/tokens/generate' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

New authentication token generated.

string string

Response

xxxxxxxxxx
 
{ "schema": "{string}"}
Copy

Enumerate Authentication Tokens

Retrieves a paginated list of authentication tokens. This endpoint allows administrators to view and manage active tokens.

Since ## 3.11.1

Auth

Path Params

start	string	The starting index for the list of tokens.
count	string	The number of tokens to retrieve from the starting index.

GET /vault_rest/tokens/{start}/{count}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/tokens/%7Bstart%7D/%7Bcount%7D' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

List of authentication tokens retrieved successfully.

object	object
Tokens	array[object]
id	string	The unique identifier of the token.
userId	string	The ID of the user associated with the token.
expires	date-time	The expiration date and time of the token.
issuedAt	date-time	The date and time the token was issued.
TotalCount	integer	The total number of authentication tokens available.

Response

xxxxxxxxxx
 
{ "Tokens": [  {   "id": "token123",   "userId": "user456",   "expires": "2024-12-31T23:59:59.000Z",   "issuedAt": "2024-11-01T10:00:00.000Z"  },  {   "id": "token789",   "userId": "user101",   "expires": "2025-01-15T12:00:00.000Z",   "issuedAt": "2024-12-01T09:00:00.000Z"  } ], "TotalCount": 2}
Copy

Recycle Authentication Token

Recycles the current authentication token, issuing a new one while invalidating the old one. This can be used to refresh a token's validity or to mitigate potential token compromise.

Since ## 3.11.1

Auth

POST /vault_rest/token/recycle

xxxxxxxxxx
 
curl --request POST \ --url 'http://localhost:8010/vault_rest/token/recycle' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Token recycled successfully, new token issued.

object object

Result

string

The result of recycling the token.

Enum: Success,Error

NewToken

string

The newly issued authentication token.

Response

xxxxxxxxxx
 
{ "Result": "Success", "NewToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
Copy

Authorization

Endpoints for checking user authorization against specific resources.

GET

/vault_rest/authorization/{resourceType}

Check Resource Authorization

Checks if the current user is authorized to access a specific resource type. This endpoint is used to enforce fine-grained access control.

Since ## 3.11.1

Auth

Path Params

resourceType

string

The type of resource to check authorization for (e.g., "file", "folder", "settings").

GET /vault_rest/authorization/{resourceType}

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/authorization/%7BresourceType%7D' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Authorization check result.

object	object
IsAuthorized	boolean	Indicates whether the user is authorized for the specified resource type.
Permissions	array[string]	A list of specific permissions the user has for the resource.

Response

xxxxxxxxxx
 
{ "IsAuthorized": true, "Permissions": [  "read",  "write" ]}
Copy

Windows Authentication

Endpoints for Windows Integrated Authentication.

GET

/vault_rest/authenticate-windows

Authenticate with Windows Credentials

Initiates authentication using Windows credentials via negotiation-based authentication. This endpoint leverages the existing Windows session of the client. The [Authorize] attribute indicates that the request is expected to carry authentication information, typically handled by the browser/server for Windows Integrated Authentication. Upon successful negotiation, an MFT API token is issued.

Since ## 3.11.1

Auth

GET /vault_rest/authenticate-windows

xxxxxxxxxx
 
curl --get \ --url 'http://localhost:8010/vault_rest/authenticate-windows' \ --header 'Authorization: Bearer {token}'
Copy

Responses

200

Windows authentication successful, API key returned.

object	object
Result	string	The result of the authentication attempt. Enum: `Success`,`ErrorServiceUnavailable`,`ErrorInvalidCredentials`,`ErrorMfaRequired`
Token	string	The authentication token (API key) if authentication was successful.
Expires	date-time	The expiration date and time of the token.
ExpiresString	string	The expiration date and time of the token as a string.
UiMessageKey	string	A key for a UI message related to the authentication result.
Message	string	A detailed message related to the authentication result.

Response

xxxxxxxxxx
 
{ "Result": "Success", "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "Expires": "2024-12-31T23:59:59.000Z", "ExpiresString": "2024-12-31T23:59:59.000Z", "UiMessageKey": "LOGIN_SUCCESS", "Message": "User authenticated successfully."}
Copy