> For the complete documentation index, see [llms.txt](https://docs.licensespring.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.licensespring.com/license-api/license-api-authorization/oauth-authorization.md).

# 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**](/license-api/license-api-authorization/api-key-authorization.md)). 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:

{% code title="Request OAuth Token (POST)" %}

```http
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
```

{% endcode %}

Example (curl):

```bash
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):

```json
{
  "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):

```json
{
  "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](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.1.1) 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
  ```

{% hint style="warning" %}
Ensure that the Date header value is set to current time. The server allows timestamps that are up to 15 minutes old.
{% endhint %}

### 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
{
  status: number,
  code: string,
  message: string
}
```

JSON Schema

```json
{
  "$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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.licensespring.com/license-api/license-api-authorization/oauth-authorization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.