> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yousonder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# One-click connect

> Let authors connect Sonder with an Allow button instead of pasting a key.

One-click connect is standard **OAuth 2.0 with the authorization code flow** (PKCE supported). The author clicks **Connect Sonder** in your app, sees exactly what you'll be able to read, clicks **Allow**, and comes back to your app connected. What you receive is an ordinary Sonder API key.

<Note>
  To use it, register your app first: email **[hello@yousonder.com](mailto:hello@yousonder.com)** with your app's name, website, logo and the exact redirect URL(s) you'll use. We send back a `client_id` and a `client_secret`.
</Note>

## 1. Send the author to Sonder

```text theme={null}
https://app.yousonder.com/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyourapp.com%2Fsonder%2Fcallback
  &state=RANDOM_VALUE_YOU_STORED
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256
```

| Parameter                                 |                                                                                                                                             |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_type`                           | Always `code`.                                                                                                                              |
| `client_id`                               | From registration.                                                                                                                          |
| `redirect_uri`                            | Must match a registered URL exactly, including any query string.                                                                            |
| `state`                                   | Any value you generate and check when the author returns, to stop cross-site request forgery. Returned unchanged.                           |
| `code_challenge`, `code_challenge_method` | Optional, recommended ([PKCE](https://datatracker.ietf.org/doc/html/rfc7636)). Send the base64url SHA-256 of a random verifier with `S256`. |

If the author isn't signed in to Sonder, they sign in first and come straight back to the Allow screen.

## 2. The author comes back

* **Allowed:** `https://yourapp.com/sonder/callback?code=…&state=…`
* **Cancelled:** `https://yourapp.com/sonder/callback?error=access_denied&state=…`

Check `state` matches what you stored.

## 3. Trade the code for a key

Codes last **10 minutes** and work **once**. Exchange from your server, never the browser:

```bash theme={null}
curl https://api.yousonder.com/v1/oauth/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=THE_CODE \
  -d redirect_uri=https://yourapp.com/sonder/callback \
  -d code_verifier=YOUR_VERIFIER
```

```json theme={null}
{
  "access_token": "sonder_live_q8Zr2mN4xT7vB1cK9pL3sD6fG0hJ5wYe",
  "token_type": "Bearer",
  "scope": "read",
  "account": { "id": "2c6f9a10-3d4b-4e8f-9a1b-7c5d3e2f1a09", "email": "jane@example.com" }
}
```

`access_token` is an API key. Use it exactly like a pasted one: `Authorization: Bearer …`. There's no refresh token because it doesn't expire.

## After connecting

* The author sees your app in Sonder under **Settings → API keys** as a **Connected app** and can disconnect it there. Your calls then return `401 api_key_revoked`.
* If the author connects again, the new key replaces the old one, which stops working.
* Errors from the token endpoint follow OAuth 2.0: `{ "error": "invalid_grant", "error_description": "…" }`. See [the reference](/api-reference/connect/exchange-a-code-for-a-key).