OAuth Configuration

OAuth authorization is an alternative authentication mechanism for the License API, available exclusively for enterprise clients.

OAuth Client ID and Secret Structure

OAuth credentials (Client ID and Secret) can be associated with different levels of specificity within the system:

• License

• Customer

• Customer Account

• Company

OAuth Token Validation Hierarchy

When validating OAuth tokens, the system follows a hierarchy of specificity:

1

Most specific: License level

Check for an OAuth secret at the License level.

2

Customer level

If not found at the License level, check at the Customer level.

3

Customer Account level

If not found at the Customer level, check at the Customer Account level.

4

Least specific: Company level

If not found at the Customer Account level, check at the Company level.

User Interface Access

• License, Customer, and Customer Account Views: OAuth settings are accessible via the OAuth tab.

• Company Level: OAuth settings can be found under Settings → Keys.

OAuth Initialization Location on Platform

Default Rotation Settings

• When creating new OAuth credentials, the system applies default rotation settings, unless overridden for specific credentials:

  • Secret Expiration Period: Defines the time before a newly generated secret expires.

  • Secret Rotation Grace Period: Specifies the period before the current secret expires, allowing for a smooth transition.

Setting the Default Rotation Settings

Enforcing OAuth Authentication

A company account may have an optional flag, is_oauth_required, when enabled:

• OAuth authentication is mandatory for all users under that company account.

• API key and shared key authentication methods are disabled.

This setting is available under Settings → Preferences.

API Error Response

If a request is sent using an API/shared key while OAuth is required, the License API will return the following error:

{
    status: 400,
    code: 'oauth_required',
    message: 'This account requires OAuth authentication'
  }

Authorization Process

To authorize with OAuth:

1

Obtain short-lived access token

Users obtain a short-lived access token using their Client ID and Secret.

2

Include token in requests

The access token must be included in the License API request headers, replacing the traditional API key or shared key.

For more details, refer to OAuth Authorization.

SDK Integration

OAuth authentication will be implemented in the SDKs to simplify integration. See your SDK specific documentation for more information.

OAuth Key Management

License Manager Permissions

License managers can:

• View a list of client IDs and secrets for the licenses and customers they manage.

• Revoke OAuth secrets.

• Manage expiration dates of OAuth secrets.

Explicit Permission Requirement

License managers can only revoke or modify expiration dates of OAuth keys if they have been granted explicit permission to do so.

OAuth Expiration Notifications

Platform users can define notification policies for OAuth key expiration. These policies trigger email notifications when:

• A secret is about to expire.

• A secret has already expired.