Track 04 · Multi-agent & integrationLesson 06 of 11
SaaS connectors and auth flows
OAuth, tokens and pagination: the integration work that is most of the job.
- Lesson library · reference
- 35 min read
- 60 min hands-on
- Pro
What you'll be able to do
01- Choose the right OAuth 2.0 grant for each connector (authorisation code with PKCE, client credentials, JWT bearer) and explain who the token represents.
- Design a connector that refreshes tokens before expiry with a single in-flight refresh, fails closed on a second 401, and never exposes a credential to the model.
- Implement cursor pagination, rate-limit signals and idempotent writes against an enterprise API, and test them against a recorded or fake upstream.
- Verify inbound webhooks with HMAC signatures, timestamp tolerance and replay protection.
- Map fields between the agent's schema and the system of record with an explicit, versioned transformation layer.
- Defend a build-versus-buy decision for connectors in front of the customer's security and platform teams.
Before you start
- Tools with scoped, auditable access: auth patterns at the tool, scopes, secret injection and audit records. This concept assumes them and goes one layer down, into the connector.
- Retries, fallbacks and failing gracefully: retry classification, jitter,
Retry-Afterand idempotency inside one agent. - Typed output: schemas, validation and tool calls: the agent-side schemas your mapping layer translates.
- Working knowledge of HTTP, JSON and the OAuth 2.0 roles (client, resource server, authorisation server).
The short version
Agents create value only when they read from and write to the systems where work is recorded: SAP for deliveries, ServiceNow for incidents, Salesforce for cases. Each of those systems has its own way of proving who you are, paging through data, limiting you and telling you when something changed. A connector is the deterministic code that hides those differences behind a small, typed interface the agent's tools call. Good connectors pick the OAuth grant that matches who is acting, refresh tokens ahead of expiry with one refresh in flight, page with cursors rather than offsets, read the upstream's rate-limit signals, send idempotency keys on every write, verify every inbound webhook before parsing it, map fields through a versioned layer, and are tested against recorded fixtures and sandboxes before they ever touch production. None of this is glamorous, and it is where most of the calendar goes.
Key takeaways:
- Pick the grant from the question "whose authority is this call?", not from what is quickest to configure.
- Tokens expire, get revoked and get rotated. Refresh proactively, refresh once on a 401, then fail closed.
- Offsets break on live data; cursors survive inserts. Never assume a page is complete because it is short.
- A webhook is untrusted input until its signature, timestamp and event ID all check out.
- Field mapping is a contract with the system owner. Version it, test it and keep it out of prompts.
Practise this in the lab
Pro lesson
The rest of this lesson is in Pro.
The mental model, worked example, field note, failure table, exercise and self-check, with the voice tutor.
- Every stage and specialisation, in full
- Every lab and every role project
- Halden weeks 2–10, on your record
- Every drill, live in the playground
- All solutions, plus the server judge
- Lab Assistant and every Teach with AI