Authorization

TL;DR

As mentioned in the API Introduction, it is possible to skip this page and dive right into experimenting on your own live data with the API. To do so, just flip through any of the API endpoints listed in the left panel that are not specifically aimed at managing authorization. Click on the beaker icon when you see an example you'd like to try.

It is not entirely necessary to understand how Vatom authorization works until you are ready to use the APIs in your own applications with support for authorizing actions on behalf of other users. You can always come back to authorization at that time.

OpenID Connect And OAuth2

When a user logs in, Vatom uses OpenID Connect to authenticate their identity. This is true of any application built on the Vatom platform, including Vatom's on internal services.

Once a user is logged in, specialized software modules can be delegated to perform actions on the user's behalf. These delegated modules may each receive limited authorization to access the resources appropriate to their functions. Vatom uses OAuth2 conventions for securely managing delegated authorization and access across software modules including Vatom's own REST APIs.

Vatom's Identity And Authorization Services

Vatom's Identity And Authorization Services are provided through a set of endpoints that share id.vatom.com as a common base URL. The most granular level of control they provide is the access token. All other Vatom REST APIs rely on these access tokens for short lived, revocable, and limited scope access to resources as appropriate to their functions.

Although the access tokens that most APIs depend upon are short lived, applications are allowed to retain authorization credentials that persist for a longer period of time. Vatom supports authorization credentials corresponding to two "Grant Types" defined by OAuth2: authorization code and client credentials. The application uses its authorization credential to request access tokens, as needed, from Vatom's authentication service.

Differences Between Grant Types

Applications that provide a user interface and authenticate the identity of the user use a credential based on the authorization code grant type. This approach includes a means of protecting the credential against misuse even when it is stored by an application residing on the user's own hardware. If an application resides on a server not exposed to the public and can be trusted with a secret, it can make use of the more streamlined client credentials approach based on an application identifier and secret key instead of an authorization code.

More details on this topic can be found under training materials for OAuth2 Grant Types and Authorization Flows.

Bootstrapping Authorization Credentials

We have so far established the following:

• APIs other Identity And Authorization Services rely on access tokens for authorization.
• An application holding an authorization credential can request access tokens as needed.

The next step is to obtain authorization credentials for your application. This is currently a manual process requiring direct contact with Vatom support via help@vatom.com.