Platform 2023.2 API authentication

API requests without authentication fail. The following authentication methods are available:

• Basic – Username and password
• Query token – Auth token in query header
• Client – Bearer token

Basic authentication

Overview

Send credentials in the HTTP request Authorization header as a base64-encoded username:password string.

Example

Replace username and password with your credentials:

1
curl -u username:password -X GET "https://localhost:3443"

HTTP request header

$
Authorization: Basic base64(username:password)

For example, if your username is user and your password is pass, the encoded header looks like this:

$
Authorization: Basic dXNlcjpwYXNz

Validate your credentials

Send a GET request to whoami to confirm you can reach theItential Platform server API and view access associated with your user:

1
curl -u username:password -X GET "https://localhost:3443/whoami"

Query token authentication

Overview

Obtain a token by sending a POST request to /login, then pass the token as a query parameter in subsequent requests.

Request a token

Send a POST request to /login with the following JSON payload:

1
{ "user": { "username": "admin", "password": "admin" } }

Example

1
curl -X POST "https://localhost:3443/login" \
2
  -H "Content-Type: application/json" \
3
  -d '{"user": {"username": "admin", "password": "admin"}}'

Response

A successful login returns an authentication token:

$
your-auth-token-here

Use the token

Include the token as a query parameter in subsequent requests:

$
?token=your-auth-token-here

Validate your token

Replace your-auth-token-here with the token returned by /login:

1
curl -X GET "https://localhost:3443/whoami?token=your-auth-token-here"

Client authentication

Overview

Obtain a bearer token by sending a POST request to /oauth/token, then pass the token in the Authorization header of subsequent requests.

Request a token

Send a POST request to /oauth/token with Content-Type: application/x-www-form-urlencoded and the following payload:

$
client_id=your-client-id&client_secret=your-client-secret&grant_type=client_credentials

Example

1
curl -X POST "https://localhost:3443/oauth/token" \
2
  -H "Accept: application/json" \
3
  -H "Content-Type: application/x-www-form-urlencoded" \
4
  -d 'client_id=123abccc123a123a12ab1ab1&client_secret=a123a123-a1a1-1a1a-a123-123a12abc1a1&grant_type=client_credentials'

Response

A successful request returns the bearer token and its expiration time:

1
{
2
  "access_token": "falksjflkasdjflkasdjfklajsdflj.eyJwcmluY2lwYWxJZCI6IjY2OWU1ZGNjOTE1ZDUxMWEzMmJmMGNhNCIsImV4cCI6MTcyMTY1OTQ4MDkwMiwiaWF0IjoxNzIxNjU1ODgwfQ.7jrB2mC9aqSdPdUvz7D-u9HghRFtnpFbYdaBH54kNZc",
3
  "token_type": "bearer",
4
  "expires_in": 3600
5
}

Use the token

Set the access_token value as your Authorization header:

$
Authorization: Bearer your-access_token-here

Validate your token

Replace your-access_token-here with the token returned by /oauth/token:

1
curl -X GET "https://localhost:3443/whoami" \
2
  -H "Authorization: Bearer your-access_token-here"