OAuth API access: scopes & provider tokens

Beyond signing users in, Atlas can hold a connection's provider tokens and broker them to your backend so you can call the provider's API (Google Calendar, GitHub repos, Slack chat, Shopify orders, …). Two pieces: which scopes you request, and how you get the token.

Requesting API scopes (opt-in, per connection)

Identity is always requested. High-value API scopes are opt-in so a sign-in-only integration keeps a clean consent screen. Each provider advertises its API scopes in the catalog:

curl "https://<fapi>/v1/oauth_providers/google" -H "Authorization: Bearer sk_…"
# → { ..., "default_scopes": [...], "api_scopes": [ { "scope": "...", "label": "...", "gated": true } ] }

gated: true means the provider requires app review / partner approval / an elevated plan for that scope — selecting it isn't enough on its own (e.g. Google restricted scopes, LinkedIn partner programs, X paid tiers).

Select the scopes on the connection:

curl -X PUT "https://<fapi>/v1/oauth_providers/google" \
  -H "Authorization: Bearer sk_…" -H "content-type: application/json" \
  -d '{"client_id":"…","client_secret":"…","scopes":["https://www.googleapis.com/auth/calendar.events"]}'

The identity defaults are always unioned in, so sign-in keeps working. (The BAPI is snake_case — client_id, not clientId.)

Getting a user's provider token

curl "https://<fapi>/v1/users/<user_id>/oauth_access_tokens/<provider>" -H "Authorization: Bearer sk_…"
# → { "object":"oauth_access_token", "provider":"google", "token":"ya29…",
#     "expires_at": 1789…, "scopes":[…], "metadata": { … } }

Atlas stores tokens encrypted, refreshes them on read (single-flight, so concurrent reads don't rotate each other away), and returns a live token.

metadata — provider handles the API needs

Some providers return a non-secret handle the API is useless without. Atlas brokers it in metadata:

• Salesforce → instance_url (the per-user API base host)

• Stripe → stripe_user_id (use with the Stripe-Account header)

• TikTok Shop → shop_id / seller_name / shop_region

Connectors worth calling out

• Google, Microsoft, GitHub, GitLab, Slack, Shopify, Salesforce, HubSpot, Dropbox, Box, Zoom, … — request api_scopes, then broker the token.

• Slack API (`slack_api`) — distinct from "Sign in with Slack": authorizes an app install and brokers a bot token (xoxb-) for chat.postMessage, conversations.*, etc. Configure the app's client_id/secret + pick bot scopes.

• GitHub App (`github_app`) — the least-privilege alternative to the coarse github OAuth App: access is the App's fine-grained per-repo permissions (set in App settings, not scopes); tokens expire and auto-refresh.

• Providers whose permissions are configured in the vendor's own app dashboard (Wix, TikTok Shop, Notion) take no scope strings here — set permissions there; Atlas brokers the resulting token.