---
title: "OAuth Package"
url: "https://docs.caracal.run/sdks/oauth/"
markdown_url: "https://docs.caracal.run/markdown/sdks/oauth.md"
description: "RFC 8693 token exchange clients for Caracal STS."
page_type: "page"
concepts: []
requires: []
---

# OAuth Package

Canonical URL: https://docs.caracal.run/sdks/oauth/
Markdown URL: https://docs.caracal.run/markdown/sdks/oauth.md
Description: RFC 8693 token exchange clients for Caracal STS.
Page type: page
Concepts: none
Requires: none

---

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

```ts
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](/guides/step-up/)
- [Mandates](/concepts/mandate/)
- [Use STS Endpoint](/api/sts/)