Overview

Applixure Authentication Server (AAS) serves as one common authentication and authorization (A&A) point for Applixure products (Analytics, Workflow and Feedback) and Applixure APIs (Feedback API, Workflow API).

📘

Note on Connect API

Analytics Connect API v1 is still based on the HTTP Basic Authentication -type authentication and authorization and does not presently support access tokens from AAS.

In the future versions of Connect API, access to the API will become available using access tokens granted from AAS.

AAS implements industry-standard OAuth2 protocol flows that allow authentication to happen with Applixure API keys or with Applixure user account login against the AAS, producing access tokens as result that then subsequently can be used to authorize API calls against those APIs.

Readers of this documentation are assumed to have a general familiarity with the OAuth2's conventions and authentication flow implementations at the technical level. If not, please refer to the following primary documentation sources:

• RFC 6749, The OAuth 2.0 Authorization Framework
• OAuth 2.0

Or to any number of other tutorials and examples found on the Internet on the subject.

Supported grants and flows

A grant is a specific flow in OAuth2 where Client requests access from AAS to specific resources (i.e. Applixure APIs) and upon authenticating successfully and AAS authorizing the request, receives the access token as a result.

Applixure Authentication Server currently supports following OAuth2 grants and their associated authentication flows:

🚧

Use of Authorization Code Grant

As Authorization Code Grant flow requires user to logon on interactively, it is not suitable for machine-to-machine use of the APIs such as with autonomous systems accessing the data.

Additionally, refresh of access tokens using Refresh Token Grant is not possible as no refresh token is issued as part of this grant.

Supported scopes

A scope in OAuth2 context refers to a specific set of abilities or permissions the caller has against the API, typically but not necessarily divided by types of objects or functionalities API offers. For instance, one scope - which is a textual value such as "profile:read" - could refer to ability to read some specific types of objects from the API. Holding that scope would enable only such operation against the API but nothing else, unless additional scopes are held by the caller. Each access token generated as part of the grant flow from the AAS has one or more scopes associated with it.

Part of the A&A flow is that the client software requests some specific scopes it needs against the API it intends to call, typically on the principle of least privilege to avoid accidentally being able to do do operations or access data for which there is no need. Depending on the permissions of the user account or API key, on behalf of which this authentication is done, all or subset of the requested scopes could then be granted by AAS for resulting access token.

If no scopes can be granted by AAS, then the A&A operation ends in error as the resulting access token would not be able to access anything without any scopes to it.

As scopes are product -specific, meaning that Analytics, Workflow and Feedback products have their own respective object models and logical organisation of the data, you will need to consult the list of scopes available from API -specific documentation:

• Available API scopes for Workflow API

📘

Scopes relate to client registration

Please note that specific set of scopes available to be requested is also dependent on *client registration covered on the next documentation page and on the API key or Applixure user account depending on which product(s) they have access to!

Applixure Environments and Accounts in scopes

Sometimes in OAuth2 implementing systems scope names themselves could include information about the logical entity the scope relate to, such as particular organisation identified by some unique id number or string. This way, one scope - say, ability to read user accounts - would only grant reading of users from that one entity.

In Applixure, for all APIs, scope itself do not carry identifying information about the specific logical boundary; either Applixure Account or Environment. When requesting access token with a given set of scopes, all of those scopes in the resulting access token are valid for all environments and accounts (as the case may be) for which the user account or API key had access to at the time of access token generation.

Concretely this means that access token is valid for all environments and accounts its granting user or API key also has. Naturally, if permissions for that user or API key is subsequently changed after generating the access token, they would not be reflected in the already generated access token for the remaining validity of such token, but will be in any new access tokens generated through refresh token (if such is used).

Base URL

Authorization Server request URLs take the following base path:

https://auth.applixure.com/