OAuth Authorization

7min
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:
Generates an access token and returns an object containing the token and associated metadata
POST
Request
Header Parameters
Content-Type
required
String
Must be: application/x-www-form-urlencoded
Form Parameters
grant_type
required
String
Must be: client_credentials
client_id
required
String
Client ID
client_secret
required
String
Client Secret
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'
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'
Responses
200
401
{
    "access_token": "TOKEN_STRING_HERE",
    "expires_in": 480,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "profile email"
}
{
    "access_token": "TOKEN_STRING_HERE",
    "expires_in": 480,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "profile email"
}
﻿
Once the access token is retrieved, it is used as an Authentication: 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:
1
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
2
Authorization
This header contains the Access Token.
Examples: 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:
TypeScript
JSON Schema
{
  status: number,
  code: string,
  message: string
}
{
  status: number,
  code: string,
  message: string
}
﻿
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)
﻿
Updated 19 Feb 2025
Did this page help you?
API Key Authorization
Request Signature