OAuth Package

The OAuth packages exchange existing subject authority for resource mandates through the STS /oauth/2/token endpoint.

Install

Ecosystem	Package
TypeScript	npm install @caracalai/oauth
Python	pip install caracalai-oauth
Go	go get github.com/garudex-labs/caracal/packages/oauth/go

Exchange inputs

Option	Meaning
Subject token	Existing user, service, agent, or application authority.
Resource	Resource identifier or audience requested from STS.
Client secret or assertion	Application authentication for client-secret flows.
Actor token	Optional actor authority for delegated exchanges.
Session ID	Subject session anchor.
Agent session ID	Agent execution anchor.
Delegation edge ID	Delegated authority anchor.
Scopes	Requested resource scopes.
TTL seconds	Requested mandate lifetime.

TypeScript example

import { OAuthClient, InteractionRequiredError } from "@caracalai/oauth";

const oauth = new OAuthClient(stsUrl, zoneId, applicationId);

try {
  const token = await oauth.exchange(subjectToken, "https://api.example.com/tickets", {
    scopes: ["tickets:read"],
    clientSecret: process.env.CARACAL_APP_CLIENT_SECRET,
  });
  console.log(token.accessToken, token.expiresIn);
} catch (error) {
  if (error instanceof InteractionRequiredError) {
    console.log("step-up required", error.challengeId);
  } else {
    throw error;
  }
}

Behavior

• Successful responses are validated for access_token, token_type, and expires_in.
• Token responses are cached by identity, resource, scopes, TTL, and credential context.
• Concurrent identical exchanges share in-flight work.
• Transient HTTP statuses are retried with bounded backoff.
• STS interaction_required responses surface as InteractionRequiredError.

Related pages

• Step-Up Re-Authentication
• Mandates
• Use STS Endpoint