Docs/Playbooks

Playbooks · 30 min

Build a robust connector with Adapter Lab

Use a repository-owned adapter contract from least-privilege auth to a real, verified canonical record.

Build the first useful slice

Ask your coding agent
Let's build the first useful slice of a <provider> connector with Brief. Start with one real provider response and map it to one canonical <entity or evidence artifact>. Study Adapter Lab, the closest existing connector, and the provider's official docs. Work out the smallest safe auth setup, fields we need, fields we must not collect, and how partial or failed reads should appear. Implement one stream, add redacted fixtures and focused tests, register it, write the setup notes, and prove it in Adapter Lab. Reuse shared auth, HTTP, pagination, cursor, secret, audit, and mapping infrastructure. Keep credentials out of chat and the repo. Finish with a diff review and an exact handoff.

Set up auth without guessing

Create OAuth apps, PATs, service clients, or signing keys in the provider's admin console. Put real values only in the approved secret store or encrypted Adapter Lab dev connection.

Ask your coding agent
Use the provider's official docs and our closest connector to walk me through the exact auth setup for <provider>. Give me the callback URL or header format, minimum scopes, environment or form field names, a harmless connection-test endpoint, and rotation and revoke behavior. Use placeholders only—never ask me to paste a real secret here.
  • OAuth: test connect, refresh, expiry, revoked consent, and missing scopes.
  • PAT/API key: use a dedicated least-privilege account; test 401, 403, and rotation.
  • Client credentials: test audience, expiry, scope response, and client auth mode.
  • Signing: reuse the shared signer; do not rebuild cryptography inside the adapter.

Prove it in Adapter Lab

Ask your coding agent
Look at this adapter's credential type and tests, then give me a redacted credential template for Adapter Lab. Tell me where each value comes from, where the real secret belongs, and how to rotate and retire the dev connection. Then run every declared stream with bounded data and trace one canonical record into the product.

Improve the foundation when the evidence points there

Ask your coding agent
Use Brief to investigate the repeated connector failure around <problem>. Compare several adapters, find the smallest shared foundation change that removes the duplication, and prove it against existing and new connectors. Preserve compatibility, add contract tests, and stop before widening the abstraction beyond the evidence.

Build the second connector differently

Ask your coding agent
Let's build a second connector for <provider> with Brief. Reuse what genuinely worked in the first connector, but verify auth, pagination, and evidence semantics instead of assuming they're the same. Build one useful stream, prove it in Adapter Lab, and save any pattern that would help the next connector.
Ask your coding agent
Let's use the <adapter> connector the way an engineer or customer would. Run the important flow against the approved sandbox, compare the result with the provider, and follow one record into the product. Check partial data, missing permissions, credential rotation, and resume behavior.
Was this guide useful?Help us make Brief easier to learn.
Ready for another workflow?Choose your next mission →