Concepts

Base URL and Realm

When you create an Auth.it project, you provide a name that will be used in the API base URL and the realm parameter in every request. For the purpose of the API, the name and realm can be used interchangeably.

The base URL is formed by adding the name as a subdomain to authit.cloud:

    {name}.authit.cloud

For example, if your project name is acme, your base URL is:

    acme.authit.cloud

Authentication

The Auth.it Admin API uses OpenID Connect to authenticate requests. This may take the form of a client_credentials grant type, if you are using the API from a server application, or you may use a user access token directly if you are using the API from a browser or other end-user client. If it is for a server application, you will have to create an API Key in your Auth.it Dashboard.

Creating an API Key

1. Visit the API Keys section of your Auth.it Dashboard.
2. Click the Add API Key button.
3. Name your key, choose permissions, and click Create.
4. Copy the Client ID and secret.

How to get an access token

Authentication is achieved by using the Authentication: Bearer <token> header in all requests. This is either the access token received from a normal authentication, or by a request directly to the OpenID Connect token endpoint.

In the client_credentials grant type, you exchange your client ID and secret for an access token. Then you use the access token to make API requests.

Auth.it offers TypeScript and Java SDKs, which abstract the process of generating and refreshing fresh access tokens.

1
POST /realms/YOUR_REALM/protocol/openid-connect/token
2
Host: YOUR_REALM.authit.cloud
3
Accept: application/json
4
Content-type: application/x-www-form-urlencoded
5
6
grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET