OAuth Authorization

Overview

The OAuth system allows for vendors to set up separate credentials for their Company, Customer Accounts, Customers or individual Licenses. Each entity has a Client ID and Client Secret (which can be set to rotate automatically). These are used to obtain an Access Token from the OAuth endpoint, to be used for access to License API endpoints (as an alternative to API Key Authorization). Vendors can enforce a company-wide mandatory OAuth rule instead of API keys.

Obtaining an Access Token

Access Tokens are short-lived secret strings used to authorize a client request on the API. To obtain an access token from the OAuth system, perform the following request:

Request OAuth Token (POST)

POST https://auth.licensespring.com/realms/user-portal/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id=CLIENT_ID_HERE
client_secret=CLIENT_SECRET_HERE

Example (curl):

curl --location 'https://auth.licensespring.com/realms/user-portal/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=CLIENT_ID_HERE' \
--data-urlencode 'client_secret=CLIENT_SECRET_HERE' \
--data-urlencode 'grant_type=client_credentials'

Successful response (200):

{
  "access_token": "TOKEN_STRING_HERE",
  "expires_in": 480,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "profile email"
}

Unauthorized response (401):

{
  "error": "invalid_client",
  "error_description": "Invalid client or Invalid client credentials"
}

Once the access token is retrieved, it is used as an Authorization: Bearer value in License API requests. The expires_in property in the response states the Access Token's TTL in seconds from the moment the token was generated.

Required Headers

Each client request must include the following headers:

• Date

  Current time given as a date string in RFC7231 format. Note that this value is always in the GMT timezone.

  Example:

  Date: Tue, 07 Jun 2014 20:51:35 GMT

• Authorization

  This header contains the Access Token.

  Example:

  Authorization: Bearer TOKEN_STRING_HERE

Ensure that the Date header value is set to current time. The server allows timestamps that are up to 15 minutes old.

Client Access Permissions

Client ID-Secret pairs can be scoped for the following resources:

• Company: Provides access to all licenses belonging to the company

• Customer Account: Provides access to all licenses associated to a Customer Account

• Customer: Provides access to all licenses associated to an individual Customer

• License: Provides access to one specific license

Each Client ID string states the type of scope used, e.g.: auth-company-100123, auth-customeraccount-200234, auth-customer-300345, auth-license-1000456

Errors in Endpoints

When calling a License API endpoint using the Access Token authorization, the system will return an error response if the Access Token is not valid. All returned errors have an HTTP status code of 400 or higher, and a response body as follows:

{
  status: number,
  code: string,
  message: string
}

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": "number" },
    "code": { "type": "string" },
    "message": { "type": "string" }
  },
  "required": [
    "status",
    "code",
    "message"
  ],
  "additionalProperties": false
}

The following errors related to Access Tokens can be returned:

oauth_token_malformed (400)

oauth_token_expired (400)

In case OAuth is enforced company-wide and a request is being sent using an API key:

oauth_required (400)