AdeliAPI
Dashboard
Documentation menu

OAuth setup

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.
  2. Open Settings → OAuth, or go directly to /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.

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} with its API key until the authoritative status is connected, failed, or expired.

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