OAuth 2.0 Authentication

How to obtain credentials

You get client_id and client_secret when you create a client as described in Managing clients. username and password are managed as described in Managing users.

The examples below use PowerShell. Set $baseUrl to your InfoLink server URL, including its application context if applicable:

$baseUrl = 'https://<host>/server'

Get access token: Client Credentials Grant

The system supports the Client Credentials Grant flow of OAuth 2.0. The client must have an associated user, whose permissions apply to API requests.

To get an access token, send a POST /api/v2/oauth2/token request with the following parameters using the application/x-www-form-urlencoded format:

• grant_type — must be set to client_credentials.
• client_id
• client_secret

For example:

Invoke-WebRequest -UseBasicParsing `
  -Uri "$baseUrl/api/v2/oauth2/token" `
  -ContentType 'application/x-www-form-urlencoded' `
  -Method POST `
  -Body @{
    grant_type    = 'client_credentials'
    client_id     = '<client_id>'
    client_secret = '<client_secret>'
  } | Select-Object -ExpandProperty Content

The server responds with HTTP 200 OK and a JSON object containing the following properties:

{
  "access_token": "<access token>",
  "refresh_token": "<refresh token>",
  "token_type": "Bearer",
  "expires_in": 1800
}

expires_in specifies the access token lifetime in seconds.

Get access token: Resource Owner Password Credentials Grant

The system also supports the Resource Owner Password Credentials Grant flow of OAuth 2.0.

To get an access token, send a POST /api/v2/oauth2/token request with the following parameters using the application/x-www-form-urlencoded format:

• grant_type — must be set to password.
• client_id
• client_secret
• username
• password

For example:

Invoke-WebRequest -UseBasicParsing `
  -Uri "$baseUrl/api/v2/oauth2/token" `
  -ContentType 'application/x-www-form-urlencoded' `
  -Method POST `
  -Body @{
    grant_type    = 'password'
    client_id     = '<client_id>'
    client_secret = '<client_secret>'
    username      = 'john@company.com'
    password      = '<password>'
  } | Select-Object -ExpandProperty Content

The server responds with HTTP 200 OK and a JSON object containing the following properties:

{
  "access_token": "<access token>",
  "refresh_token": "<refresh token>",
  "token_type": "Bearer",
  "expires_in": 1800
}

For both grant types, you can alternatively provide the client credentials through HTTP Basic authentication instead of including client_id and client_secret in the form body. Do not combine these two client authentication methods.

Use access token

For either grant, use the obtained access token with API requests by adding the following HTTP header:

Authorization: Bearer <access token>

For example, to list applications accessible to the authenticated user:

Invoke-WebRequest -UseBasicParsing `
  -Uri "$baseUrl/api/v2/apps" `
  -Method GET `
  -Headers @{
    Authorization = 'Bearer <access token>'
  } | Select-Object -ExpandProperty Content

The user’s permissions determine which resources and operations are available.

API v1 and API v2 share the same OAuth sessions. An access token obtained through either version can be used with both versions.

Refresh access token

If an access token is invalid or expired, a protected API v2 endpoint responds with HTTP 401 Unauthorized and the following JSON object:

{
  "code": "invalid_grant",
  "message": "Credentials or token is invalid or expired"
}

The response also includes a WWW-Authenticate header identifying the invalid Bearer token.

You can obtain a new access token by sending a POST /api/v2/oauth2/token request with the following parameters using the application/x-www-form-urlencoded format:

• grant_type — must be set to refresh_token.
• refresh_token

For example:

Invoke-WebRequest -UseBasicParsing `
  -Uri "$baseUrl/api/v2/oauth2/token" `
  -ContentType 'application/x-www-form-urlencoded' `
  -Method POST `
  -Body @{
    grant_type    = 'refresh_token'
    refresh_token = '<refresh token>'
  } | Select-Object -ExpandProperty Content

If the refresh token is valid, the server responds with HTTP 200 OK and a new access token:

{
  "access_token": "<new access token>",
  "refresh_token": "<same refresh token>",
  "token_type": "Bearer",
  "expires_in": 1800
}

The previous access token immediately stops working. The refresh token retains its value and original expiration time.

If the refresh token is invalid or expired, the server responds with HTTP 400 Bad Request:

{
  "error": "invalid_grant",
  "error_description": "Credentials or token is invalid or expired"
}

To continue, obtain a new access token using the Client Credentials Grant or Resource Owner Password Credentials Grant.

Token lifetime and error responses

By default:

• Access tokens expire after 30 minutes.
• Refresh tokens expire 24 hours after their creation.
• Tokens are case-sensitive.
• Restarting the server invalidates all tokens because OAuth sessions are stored in memory.

The token endpoint returns OAuth error objects containing error and error_description. Other API v2 endpoints use code and message.

For example, an unsupported grant type returns HTTP 400 Bad Request:

{
  "error": "unsupported_grant_type",
  "error_description": "Unsupported grant_type"
}

Token responses include Cache-Control: no-store and Pragma: no-cache.