Authentication
export const meta = { title: 'API authentication', description: 'Understand how browser and API authentication work together for authenticated API testing.', tags: ['reference', 'api', 'authentication'], };
01How authentication works
Authentication can come from two places:
- Direct API authentication that you configure on the request or credential
- Browser authentication captured from a logged-in browser session
Use browser-backed authentication when your app signs users in through a web flow and then stores tokens for later API calls. This helps you test APIs behind modern single-page app sign-in flows without manually rebuilding headers for each request.
02Web app sessions
The web app uses cookie-based authentication (access + refresh token rotation).
03Browser and API authentication
Use Auth Handoff in your credential setup to forward authentication from a browser session into API requests.
- Sign in through the browser flow you already use in your test.
- Open the credential you want to use for API requests.
- Configure Auth Handoff to reuse authentication captured during the browser session.
- Run your API request after the browser sign-in step completes.
When Auth Handoff is enabled, API-sequence tests can reuse tokens captured from the browser session instead of requiring you to recreate auth headers by hand.
| Supported source | What you can reuse |
|---|---|
| Cookies | Session-based auth already present in the browser |
localStorage | Tokens stored by SPA login flows |
| IndexedDB | Tokens stored by SDK-driven auth flows |
Use this model when your app authenticates in the browser first and your downstream API calls depend on that same signed-in state.
Limits and expected behavior
- Use browser-backed execution when the API request depends on auth captured during the browser session.
- Make sure the browser sign-in step runs before any API request that depends on Auth Handoff.
- Expect the best results with apps that store usable session or token data in cookies,
localStorage, or IndexedDB. - If your app refreshes tokens during the session, rerun the sign-in flow if the API request starts with expired or missing auth.
04Authentication surfaces
Canary supports API authentication in these surfaces:
| Surface | Use it for |
|---|---|
| Direct API authentication | Add auth directly on a request or credential when you already have the required token, secret, or header value. |
| Browser-backed authentication with Auth Handoff | Reuse auth captured during a browser sign-in flow for downstream API requests. |
| Claude and other MCP-compatible clients via OAuth | Connect external MCP clients to Canary without managing API keys manually. See /docs/integration/claude. |
Use the Claude integration when you want to authenticate an external MCP client to Canary through a guided OAuth flow. Use direct API authentication or Auth Handoff when you are testing API requests inside Canary.
05OAuth flows
OAuth is also available as an authentication surface for external MCP clients such as Claude. Instead of creating and copying API keys by hand, start from the Claude integration setup and complete the OAuth prompts for your client.
For setup steps and supported clients, see /docs/integration/claude.
06Troubleshooting
If authentication does not carry over to the API request, check these items first:
- Confirm the browser step completed successfully and the user is signed in.
- Confirm the API request runs in the same test flow after the browser sign-in step.
- Confirm your app stores auth in cookies,
localStorage, or IndexedDB. - Confirm the credential has Auth Handoff enabled.
- Rerun the flow if your app rotates or refreshes tokens during sign-in.
If your SPA uses a provider that refreshes tokens in the background, run the browser sign-in immediately before the dependent API request. This improves reliability for flows that behave like Firebase-style session refresh.
If you still cannot reuse browser auth, fall back to direct API authentication on the request or credential and compare the results.
07Docs connect
The docs site can optionally “connect” a logged-in user via /docs/connect and a short-lived bearer token.