Access Tokens

Obtain token using username / password

Example Request:

curl "https://controller-host:8001/api/v2/auth" \
	-X POST \
	-d password="mypassword" \
	--data-urlencode username="jsmith@example.com"

Example Response:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gU21pdGgiLCJhZG1pbiI6dHJ1ZX0.LfFQV0anBnn40BJ-CL3XSDUAcbqQw8Xm7sDKNVHrR9U"

Retrieve a user's access token that can be used for token authentication, by logging in with username and password. This token is valid for a configurable duration (default 30 days). Once the token expires, this endpoint will need to be called again to obtain a new access token.

This endpoint does not require authentication.

HTTP Request

POST /api/v2/auth

Request Parameters

Name	Type	Description	Default Value
username	string	Username to authenticate with
password	string	Password to authenticate with

Returns

Returns a valid access token in JSON Web Token (JWT) format.

Obtain token using SAML (Step 1)

Example Request:

curl "https://controller-host:8001/api/v2/auth/saml/gen-secret" \
	-X GET

Example Response:

"eyJhbGciOiJ...75TOc0CXKW"

This is the first step when performing SAML authentication via the REST API. It returns a temporary secret token (called SECRET below), which is used to complete SAML authentication via the REST API.

About SAML Authentication

When SAML authentication is enabled in MT Edge, this flow will allow a REST API Client to log in on behalf of an end-user. Please note that the login credentials never flow through MT Edge server. They are handled by the trusted SAML Identity Provider Web site (e.g Azure).

Authentication Flow

The authentication flow consists of three steps:

• Step 1: The client calls the REST API endpoint /api/v2/saml/gen-secret to generate a temporary secret, called SECRET below.
• Step 2: The client opens the following URL in a Web browser: /api/v2/saml/init?secret=SECRET.
• Step 3: The client calls /api/v2/saml/wait?secret=SECRET. When the end-user completes the authentication started at step B, this call will return the authentication token.
• This authentication token can be used the same way as the token returned by /api/v2/auth.

Please note the difference between calls:

• Step 1 and Step 3 are regular REST API calls. They return values.
• Step 2 consists of opening a URL in a Web browser allowing the user to log in. It indirectly causes Step 3 to return upon success, but it does not return a value itself.

Note regarding order of the calls:

Step 2 and Step 3 can be performed in any order. If Step 3 is performed first, the API client would have to be multi-threaded, as the call blocks until Step 2 completes the login in the browser. It is generally easier to perform Step 2 first, as Step 2 returns immediately, allowing the API client to call Step 3 right away.

This endpoint does not require authentication.

HTTP Request

GET /api/v2/auth/saml/gen-secret

Returns

Returns a temporary secret token used in Step 2 and Step 3 of authentication.

Obtain token using SAML (Step 2)

Example Request:

curl "https://controller-host:8001/api/v2/auth/saml/init?secret=eyJhbGciOiJ...75TOc0CXKW" \
	-X GET

This is the second step when performing SAML authentication via the REST API.

The Client uses the secret token obtained at Step 1 above to open a web page in the Web browser. This web page will allow the end-user to complete the SAML login on the SAML Identity Provider web site.

For a complete description of the workflow, please see Step 1 (/api/v2/auth/saml/gen-secret) above.

This endpoint does not require authentication.

HTTP Request

GET /api/v2/auth/saml/init

Request Parameters

These parameters should be added to the URL as a query string.

Name	Type	Description	Default Value
secret	string	Secret token previously obtained in Step 1 by calling /api/v2/auth/saml/gen-secret

Returns

Returns a temporary secret token used in Step 2 and Step 3 of authentication.

Obtain token using SAML (Step 3)

Example Request:

curl "https://controller-host:8001/api/v2/auth/saml/wait?secret=eyJhbGciOiJ...75TOc0CXKW" \
	-X GET

Example Response:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gU21pdGgiLCJhZG1pbiI6dHJ1ZX0.LfFQV0anBnn40BJ-CL3XSDUAcbqQw8Xm7sDKNVHrR9U"

Retrieves an access token used for authentication in API calls. The end user first logs in via SAML using a Web browser. A successful SAML login will produce an authentication token used for API calls. This token is valid for a configurable duration (default 12 hours). Once the token expires, this endpoint will need to be called again to obtain a new access token.

For a complete description of the workflow, please see Step 1 (/api/v2/auth/saml/gen-secret) above.

This endpoint does not require authentication.

HTTP Request

GET /api/v2/auth/saml/wait

Request Parameters

These parameters should be added to the URL as a query string.

Name	Type	Description	Default Value
secret	string	Secret token previously obtained in Step 1 by calling /api/v2/auth/saml/gen-secret

Returns

Returns a valid access token in JSON Web Token (JWT) format.