Skip to content
Kessel

Package: auth

The auth package defines generic authentication abstractions that are usable across multiple protocols.

Interfaces

AuthRequest

Object used to perform authenticated HTTP requests. In languages where such constructs are already provided (e.g. python, see [1]), they should be used instead of this object to take advantage of the existing ecosystem.

This can be created from the OAuth2ClientCredentials Object by using oauth2AuthRequest.

[1] https://requests.readthedocs.io/en/latest/user/authentication/

Methods

  • configureRequest(request: Request)

    Configures the HTTP request as needed to use a specific authorization type. This method allows adopters to implement a specific authorization type depending their environment.

    request: Request

    Request or equivalent object used in the language.

Classes

OAuth2ClientCredentials

Credentials class implementing the OAuth 2.0 Client Credentials grant. Retrieves and refreshes access tokens from a direct OAuth 2.0 token endpoint (tokenEndpoint), which MUST be an HTTPS URL, using the Client Credentials grant. Token endpoint requests retry transient connection and timeout errors, HTTP 429 responses, and HTTP 5xx responses with bounded exponential backoff and jitter. Other errors are returned without retrying.

Constructors

  • OAuth2ClientCredentials(clientId: string, clientSecret: string, tokenEndpoint: string, retry?: RetryOptions)

    Initialize the credential helper.

    clientId: string

    OAuth 2.0 client identifier

    clientSecret: string

    OAuth 2.0 client secret

    tokenEndpoint: string

    OAuth 2.0 token endpoint HTTPS URL

    retry?: RetryOptions

    Optional retry policy for token endpoint requests. Defaults to 3 retries with full-jitter exponential backoff capped at 0.5, 1, and 2 seconds. Set maxRetries to 0 to disable retries.

Methods

  • getToken(forceRefresh?: boolean): RefreshTokenResponse

    Obtains a valid token for the client. If forceRefresh is set to true, a new token is fetched and cached regardless of the current token’s expiry. The cached token is returned when it does not expire in the next 5 minutes (300 seconds). Otherwise, a new one is fetched and cached.

    Implementations must be thread-safe.

    forceRefresh?: boolean

    Set to true to bypass the cache and fetch a new token (default: false). NOT RECOMMENDED. Force with caution!

RetryOptions

Configuration for bounded retries on transient OAuth token endpoint failures. Retry behavior is applied only while obtaining a token, not to arbitrary API calls or OIDC discovery. Implementations must preserve thread-safe token caching and coalesce concurrent refresh attempts.

Properties

  • maxRetries: integer

    Maximum number of retries after the initial request (default: 3; 0 disables retries).

  • baseDelay: number

    Initial exponential backoff delay in seconds (default: 0.5).

  • maxDelay: number

    Maximum exponential backoff delay in seconds (default: 2.0).

  • jitter: string

    Jitter mode, either full (default) or none.

RefreshTokenResponse

Parsed token data

Properties

  • accessToken: string

    OAuth 2.0 token

  • expiresAt: Datetime

    Token's expiration time.

OIDCDiscoveryMetadata

Parsed OIDC discovery document exposing useful endpoints.

Properties

  • tokenEndpoint: string

    OAuth 2.0 token endpoint URL advertised by the provider

Functions