# OAuth setup

> Register exact client redirect URIs and return customers to your application after provider authorization.

Canonical: <https://www.tryadeli.com/docs/oauth>

Adeli hosts the provider authorization flow, stores provider tokens, and returns
your customer's browser to your application. Before a connect request can use a
`redirectUrl`, register that exact URI for your organization.

## Register a redirect URI

1. Sign in to the [Adeli dashboard](https://app.tryadeli.com/sign-in).
2. Open **Settings → OAuth**, or go directly to
   [`/settings/oauth`](https://app.tryadeli.com/settings/oauth).
3. Enter the complete callback URI in your application, such as
   `https://client.example/oauth/adeli`.
4. Select **Register URI**.

Owners and admins can add or remove registrations. Members can view them. Add a
separate URI for every production, staging, and local callback your integration
uses.

> **Note: The complete URI must match**
>
> Adeli matches the normalized scheme, host, port, path, and fixed query string.
> Registering `https://client.example/oauth/adeli` does not authorize
> `https://client.example/another-path`. Wildcards and fragments are not
> supported.

Production URIs must use HTTPS. For local development only, HTTP is accepted on
`localhost` and `127.0.0.1`, including a port:

```text
http://localhost:3001/oauth/adeli
http://127.0.0.1:3001/oauth/adeli
```

## Client return URI versus provider callback URI

Your registered URI is the **client return URI**. It belongs to your application
and receives the browser after Adeli has processed authorization.

The social provider instead returns to an **Adeli provider callback URI**, such
as `https://app.tryadeli.com/api/youtube/callback`. Adeli owns the provider apps,
client secrets, callback registration, token exchange, and refresh cycle. You do
not create provider apps or register Adeli's callback URLs yourself.

## Start the authorization flow

Call the connect endpoint from your server with your API key. `redirectUrl` must
match one of the active organization's registered URIs:

```bash
curl --fail-with-body -X POST \
  "$ADELI_URL/api/v1/profiles/$PROFILE_ID/connect" \
  -H "Authorization: Bearer $ADELI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"instagram","redirectUrl":"https://client.example/oauth/adeli"}'
```

The response contains an `authUrl` and connection-session `id`. Open `authUrl`
in **your customer's browser**; do not fetch it from your backend. The customer
authorizes directly with the provider.

You may omit `redirectUrl` and poll the session without a browser return.

## Handle the browser return

After the provider callback finishes, Adeli sends the browser to your registered
URI with these query parameters:

- `connectionSessionId` — the connection session to poll.
- `status` — its status when the browser was redirected.
- `accountId` — present when an account connected successfully.
- `workflowId` — a UI hint for the provider workflow.

Treat them only as a browser hint. Your server must poll
[`GET /api/v1/profiles/{profileId}/connect/{connectionSessionId}`](https://www.tryadeli.com/docs/api/connect/get-connection-session)
with its API key until the authoritative status is `connected`, `failed`, or
`expired`.

> **Warning: Keep the API key on your server**
>
> The redirect handler can send the session id to your backend, but it must not
> expose the Adeli API key in browser code. One key can act on every profile in
> its organization.

## Change or remove a URI

Add the replacement first, update your application to send it as `redirectUrl`,
and then remove the old registration. Removing a URI prevents new connection
sessions from using it immediately. A session created before removal stores the
previously accepted URI and may finish during its ten-minute lifetime.

An invalid, insecure, or unregistered `redirectUrl` returns
`400 invalid_redirect_uri` before Adeli creates a connection session.

## Next steps

- [Quickstart](https://www.tryadeli.com/docs/quickstart) — create a key, connect an account, and publish.
- [Connect overview](https://www.tryadeli.com/docs/api/connect) — the full browser and provider flow.
- [Start connection](https://www.tryadeli.com/docs/api/connect/start-connection) — request and response contract.
- [Authentication](https://www.tryadeli.com/docs/authentication) — API-key scope and storage.