Guides

Use Guides after Get Started when you have a concrete integration job. These pages teach complete application-integrator and resource-server workflows; package and API pages remain the source for signatures and wire fields.

When to use this section

• Application integrators start with an SDK guide, then route outbound calls through Gateway or caracal run.
• Resource-server integrators start with Gateway routing or the adapter matching their server framework.
• Platform integrators use the modeling, resource/provider, policy, testing, and audit workflows before production traffic.

Choose by Task

Task	Start with
Map your architecture onto Caracal	Model Your Application in Caracal
Serve many of your own customers from one deployment	Serve Your Own Customers
Define protected targets and upstream credentials	Define Resources and Providers and Provider Recipes
Write and activate authorization logic	Author Policy Data and Activate a Policy Set
Debug an authorization result	Debug Authorization Decisions
Add Caracal to app code	TypeScript SDK, Python SDK, or Go SDK
Run an existing process with Caracal tokens	Run an Agent with caracal run
Protect a Gateway-routed HTTP upstream	Protect a Gateway-Routed HTTP API
Protect a resource server in process	Express, FastAPI, FastMCP, Go net/http, or MCP server
Add Delegation, audit export, or Approval	Delegation, Audit Stream, or Human Approval
Notify approvers when a hold is raised	Approval Notifications
Make retries safe for side-effecting actions	Safe Retries and Idempotency
Test an integration without a live stack	Test Caracal Integrations
Govern LangChain, LangGraph, or CrewAI	Govern Agent Frameworks
Plan a production integration	Production Integration Patterns

Recommended Order

flowchart LR
  Model["Model app"]
  Resource["Define resources and providers"]
  Policy["Author policy"]
  Activate["Activate policy"]
  App["Integrate app"]
  Protect["Protect boundary"]
  Debug["Trace and debug"]

  Model --> Resource --> Policy --> Activate --> App --> Protect --> Debug

Surface Boundaries

Use the right surface for each task:

Surface	Use for
caracal up, down, status, upgrade, purge, allowlist, and run	Local runtime lifecycle, Console sign-in admission, and subprocess injection.
Console	Human-facing zone, application, provider, resource, policy, session, audit, explanation, delegation, and diagnostic workflows.
Admin API and @caracalai/admin	Automation for the same control-plane objects.
SDKs and adapters	Application integration, context propagation, mandate exchange, and mandate verification.

Before You Start

You need a running Caracal runtime, a zone, an application, at least one resource, and an active policy set. First Protected Call creates that baseline.

Expected Outcome

After following one path through the table, an allowed call reaches exactly one protected resource, a denied call fails before protected work runs, and both outcomes can be found by request ID in Audit.

Common mistake

Use the linked SDK and package reference for exact release signatures. Guides own sequencing, boundary choices, validation, and recovery - not duplicate API catalogs.

Next Step

Choose the first unfinished job in Choose by Task. For a new integration, start with Model Your Application in Caracal.