UNI-Cloud API 1.1

Homepage Integration

Overviewchevron_right

Authorization User Roles HTTP Methods Real-Time Data Streaming Status Codes Content Types Errors Pagination Rate Limiting Versioning

Endpointschevron_right

Subscriptions Devices Logs Profiles Survey GeoJson (Beta)

API Changelog

AuthenticationBearer TokenPrerequisitesStep-By-Step GuideExampleRefreshing an Access TokenErrorsToken SizeIdentity TokenSecurity
Please beware that the documentation is still in Alpha!

linkAuthentication

To access the marXact API, you will need to have an authorized access token.

The API uses OAuth 2.0 for authentication, and all requests must be made over HTTPS, meaning all requests must be made over a secure connection. The Authorization header is used to authenticate all requests.

1linkGET https://api.marxact.com/endpoint

2linkAuthorization: Bearer API_TOKEN

Please note that you can choose to send data as JSON, form or query params in all POST requests on this page, as long as the appropriate Content-Type header is included.

linkBearer Token

Before using the API, you'll need to get get in touch to receive the credentials - client_id and client_secret.
When requesting the credentials, be sure to tell us the,

  1. Name of the application
  2. Description of the Application Usage.
  3. Contact Details
  4. URL or IP-Address where the requests will be coming from.

These credentials are then used to request an access token, which is necessary for all future API requests.
The access token is usually valid for two days, and a refresh token can be used to request a new access token when the current one expires.


linkPrerequisites
  • client_id
  • client_secret
linkStep-By-Step Guide
  1. Prepare a POST-request to,
    • https://login.marxact.com/connect/token
  2. Set the Content-Type of the request to,
    • application/x-www-form-urlencoded
  3. Set the arguments in the body,
    • client_id=<id>&client_secret=<secret>&grant_type=password&username=<username>&password=<password>&scope=offline_access,role,UNICloudApi
  4. Send the POST-request.
  5. Retrieve the access_token,
    • response['access_token'];
Identity Server
1linkhttps://login.marxact.com/connect/token

Access Token Arguments
chevron_right

  • client_idstring

    Your OAuth client ID.

  • client_secretstring

    Your OAuth client secret.

  • grant_typeGrantType

    The OAuth Flow.
    • Must be password

  • usernamestring

    The username of the user.

  • passwordstring

    The password of the user.

  • scopeScope

    The granted data.
    • Must be offline_access, role, and UNICloudApi.

The access_token is the token that you will use to authenticate subsequent API requests. Furthermore, the expires_in field indicates the number of seconds the token is valid for, this is typically two days. Finally, the refresh_token can be used to request a new access_token when the current one expires.

Response Model
chevron_right

  • access_tokenstring

    The token as issued by the authorization server.

  • token_typestring

    The type of token- this will always be Bearer.

  • expires_instring

    The duration of time the access token is granted for.

  • refresh_tokenstring

    The refresh token that can be used to obtain another access token.
linkExample

Here is an example of a request using cURL:

POST
1link$curl -X POST \

2link$  https://login.marxact.com/connect/token \

3link$  -H 'Content-Type: application/x-www-form-urlencoded' \

4link$  -d 'client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=password&username=USERNAME&password=PASSWORD'

If the request is successful, you will receive a response in the following format

response
1link{

2link    "access_token": "ACCESS_TOKEN",

3link    "token_type": "Bearer",

4link    "expires_in": 3600,

5link    "refresh_token": "REFRESH_TOKEN"

6link}

linkRefreshing an Access Token

To refresh an access token, make a POST request to the same URL as above with the following parameters in the request body: Here is an example of a request using cURL: 

1link$curl -X POST \

2link$    https://login.marxact.com/connect/token \

3link$    -H 'Content-Type: application/x-www-form-urlencoded' \

4link$    -d 'client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN'

If the request is successful, you will receive a response in the same format as above, with a new access_token and refresh_token.

Refresh Token Arguments
chevron_right

  • client_idstring

    Your OAuth client ID.

  • client_secretstring

    Your OAuth client secret.

  • grant_typeGrantType

    The OAuth Flow.
    • Must be refresh_token

  • refresh_tokenstring

    The refresh token that was returned when the original access token was issued.
    • Must be offline_access, role, and UNICloudApi.
linkErrors

Requesting a token from the Identity Server can encounter various errors during the authorization process. The error is received as part of the error response returned from the OAuth 2.0 Token Authorization endpoint. This error response is returned when the authorization process fails for any reason, including the error conditions described in the previous answer. The error response is typically in JSON format and includes a descriptive error message, an error code to indicate the specific type of error that occurred, and any additional parameters that may be relevant to the error condition. The returned errors are given in the following format,

1linkHTTP/1.1 400 Bad Request

2linkContent-Type: application/json

3link

4link{

5link    "error": "error_type",

6link    "error_description": "description"

7link}

To retrieve the error, you would typically check the HTTP status code of the response. If the status code is 400 Bad Request or 401 Unauthorized, then you would parse the JSON error response to get the error code and error description. This information can then be used to determine how to handle the error and present it to the user in a meaningful way.

Error Types
chevron_right

  • invalid_request

    Occurs when the request is missing required parameters or cintains invalid parameters.

  • invalid_client

    Occurs when the client authentication fails, such as when the client ID or secret is incorrect.

  • invalid_grant

    Occurs when the provided authorization grant (such as an authorization code) is invalid, expired, or revoked.

  • unauthorized_client

    Occurs when the client is not authorized to make the request.

linkToken Size

Expect that the length of all access token types will change over time as we changes to what is stored in them and how they are encoded. You can expect that they will grow and shrink over time. Please use a variable length data type without a specific maximum size to store access or refresh tokens.

linkIdentity Token

The ID token resembles the concept of an identity card, in a standard JWT format, signed by the OpenID Provider. The content of the token is described below.

Identity Token Features
chevron_right

  • nbfuint

    (not before time): Time before which the JWT must not be accepted for processing.

  • expuint

    (expiration time): Time after which the JWT expires.

  • issURL

    (issuer): Issuer of the JWT.

  • audstring[]

    (audience): Recipient for which the JWT is intended.

  • client_idstring

    The identifier of the Client.

  • subGUID

    (subject): The subject of the JWT (user). This sufficies the 'user_id' on any endpoint.

  • auth_timeuint

    Authenticated Time.

  • idpstring

    (identity provider).

  • roleRole

    The role of the user. This is further explained in User Roles.

    Role
    chevron_right
    • Admin
    • FreeAdmin
    • Manager
    • FreeManager
    • User
    • FreeUser
    • ReadOnly

  • sub_expirationMM/DD/YYYY

    Expiration date of the subscription.

  • tidGUID

    Tenant ID.

  • sub_typeSubType

    The subscription type.
    SubType
    chevron_right
    • Basic
    • Enterprise

  • given_namestring

    The User's Given Name.

  • family_namestring

    The User's Surname.

  • emailstring

    The User's Email.

  • namestring

    The User's Name.

  • preferred_usernamestring

    The User's Preferred Username.

  • localeLocale

    The User's Locale.

  • free_accessboolean

    Whether the user has free access.

  • uni_supportboolean

    Whether the user has uni support.

  • scopeScope[]

    The Scope of the User.

  • amrstring[]

    (Authentication Methods References).
1link{

2link "nbf": 0123456789,

3link "exp": 0123456789,

4link "iss": "https://login.marxact.com",

5link "aud": [

6link   "https://login.marxact.com/resources",

7link ],

8link "client_id": "client_id",

9link "sub": "ab1cd234-5678-910e-fg11-h1213141516i",

10link "auth_time": 0123456789,

11link "idp": "local",

12link "role": [

13link   "User",

14link   "ReadOnly",

15link ],

16link "sub_expiration": "MM/DD/YYYY",

17link "tid": "ab1cd234-5678-910e-fg11-h1213141516i",

18link "sub_type": "Enterprise",

19link "given_name": "name",

20link "family_name": "surname",

21link "email": "email@marxact.com",

22link "name": "name",

23link "preferred_username": "preferred_username",

24link "locale": "en",

25link "free_access": "False",

26link "uni_support": "True",

27link "scope": [

28link   "profile",

29link   "email",

30link   "role",

31link ],

32link "amr": [

33link   "pwd"

34link ]   

35link}


Once you have your API key, you can include it in your requests as a query parameter or in the request headers. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

linkSecurity

Your API keys carry many privileges, so be sure to keep them secure and not share it with anyone! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. If you believe your API key has been compromised, please contact us immediately.

marXact
Knowledge Base
Changelog