---
title: "Identity Package"
url: "https://docs.caracal.run/sdks/identity/"
markdown_url: "https://docs.caracal.run/markdown/sdks/identity.md"
description: "JWT verification packages for mandate claims, scopes, targets, agents, delegation, and hop count."
page_type: "page"
concepts: []
requires: []
---

# Identity Package

Canonical URL: https://docs.caracal.run/sdks/identity/
Markdown URL: https://docs.caracal.run/markdown/sdks/identity.md
Description: JWT verification packages for mandate claims, scopes, targets, agents, delegation, and hop count.
Page type: page
Concepts: none
Requires: none

---

The identity packages verify Caracal mandate JWTs. Use them when you are building a connector, transport, or custom resource-server boundary that accepts mandates directly.

## Install

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

Node packages target Node `>=22`; Python packages require Python `>=3.12`.

## Verification inputs

| Option | Meaning |
| --- | --- |
| `issuer` / `Issuer` | Expected STS issuer. |
| `audience` / `Audience` | Expected audience for the mandate. |
| `zoneId` / `expected_zone_id` / `ZoneID` | Zone claim check. When omitted, the verifier reads the unverified `zone_id` claim to select the zone keyset, then proves it through signature verification. |
| `requiredScopes` / `required_scopes` / `RequiredScopes` | Scopes every accepted mandate must contain. |
| `requiredTargets` / `required_targets` / `RequiredTargets` | Target resources every accepted mandate must include. |
| `requiredUse` / `required_use` / `RequiredUse` | Token use, usually `resource`. |
| `requireAgent` / `require_agent` / `RequireAgent` | Require agent-session claims. |
| `requireDelegation` / `require_delegation` / `RequireDelegation` | Require a delegation edge. |
| `requireChainContains` / `require_chain_contains` / `RequireChainContains` | Require an application in the delegation chain. |
| `maxHopCount` / `max_hop_count` / `MaxHopCount` | Cap delegation chain depth. |

## TypeScript example

```ts
import { verify } from "@caracalai/identity";

const claims = await verify(token, {
  issuer: "https://sts.example.com",
  audience: "https://api.example.com",
  zoneId: "zone_prod",
  requiredScopes: ["tickets:read"],
  requiredTargets: ["https://api.example.com/tickets"],
});
```

## JWKS caching

STS signing keysets are zone-scoped: every fetch hits `{issuer}/.well-known/jwks.json?zone_id={zone}` and is cached per issuer and zone. TypeScript verifiers use an in-memory JWKS cache by default. Build a cache explicitly when a resource server wants shorter local-development TTLs, a custom fetch implementation, or warmup during service boot.

```ts
import { createJwksCache, verify } from "@caracalai/identity";

const jwksCache = createJwksCache({ ttlMs: 300_000, fetchTimeoutMs: 5_000 });
await jwksCache.warm("https://sts.example.com", "zone_prod");

const claims = await verify(token, {
  issuer: "https://sts.example.com",
  audience: "https://api.example.com",
  zoneId: "zone_prod",
  jwksCache,
});
```

Go and Python identity packages also cache issuer JWKS metadata in memory. Python exposes `warm_jwks(issuer, zone_id)` for service boot; Go callers can warm the cache with `GetJWKSContext(ctx, issuer, zoneID)`.

## Failure classes

| Error | Meaning |
| --- | --- |
| `TokenInvalidError` | Signature, issuer, audience, expiry, use, or claim validation failed. |
| `ZoneInvalidError` | The token zone did not match the expected zone. |
| `ScopeInsufficientError` | A required scope is missing. |
| `AgentIdentityRequiredError` | The verifier requires an agent identity. |
| `DelegationRequiredError` | The verifier requires delegated authority. |
| `ChainMismatchError` | The delegation chain is missing a required application. |
| `HopCountExceededError` | The mandate exceeds the configured hop limit. |

## When to Use MCP Auth Transport

Use [MCP Auth Transport](/sdks/transport-mcp/) when you also need revocation checks, reusable verifier defaults, bearer-header parsing, and safe debugging hints. Use the identity package directly when you are composing your own verifier or connector boundary.