Connections

Connections let you link external services (like Facebook) to an organization. Once connected, your app can use the stored access token to make API calls on behalf of the org — for example, managing Facebook Ads.

Concepts

Org Connections vs User Connections

Mushu supports two types of connections:

Type	Owner	Use Case
Org Connection	Organization	Shared service access (e.g., company Facebook Ads account)
User Connection	Individual user	Personal service access (e.g., user's own Facebook profile)

Org connections are created by admins/owners and accessible to all org members. User connections are created by and accessible only to the individual user.

Setup

1. Configure Facebook Credentials

Before connecting, configure Facebook credentials for your app. You can set these on the auth provider or on a connection config:

POST /apps/{'{app_id}'}/connections
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{'{'}
  "service": "facebook",
  "enabled": true,
  "facebook_app_id": "YOUR_FB_APP_ID",
  "facebook_app_secret": "YOUR_FB_APP_SECRET",
  "facebook_scopes": ["ads_read", "ads_management"]
{'}'}

Note: If you don't provide Facebook credentials on the connection config, Mushu falls back to your auth provider's Facebook credentials.

2. Initiate OAuth Flow (Org Connection)

An admin starts the OAuth flow by redirecting to the authorize endpoint:

GET /apps/{app_id}/orgs/{org_id}/connections/facebook/authorize?redirect_uri=https://yourapp.com/connected
Authorization: Bearer ADMIN_TOKEN

This redirects to Facebook's OAuth consent screen. After the user authorizes, Facebook redirects back to Mushu, which stores the token server-side and redirects to your redirect_uri with ?connection=facebook&status=success&scope=org.

3. Initiate OAuth Flow (User Connection)

For user-level connections, the flow is similar but uses the user connections endpoint:

GET /connections/facebook/authorize?redirect_uri=https://yourapp.com/connected
Authorization: Bearer USER_TOKEN

Using Connections

List Org Connections

GET /apps/{app_id}/orgs/{org_id}/connections
Authorization: Bearer YOUR_TOKEN

Response:

{'{'}
  "connections": [
    {'{'}
      "connection_id": "abc-123",
      "service": "facebook",
      "status": "active",
      "external_account_name": "Acme Ads",
      "connected_at": "2026-01-15T...",
      "token_expires_at": "2026-03-15T..."
    {'}'}
  ]
{'}'}

Get Access Token

To make API calls with the connection's token:

GET /apps/{app_id}/orgs/{org_id}/connections/{connection_id}/token
Authorization: Bearer YOUR_TOKEN

Response:

{'{'}
  "connection_id": "abc-123",
  "service": "facebook",
  "access_token": "EAAGm0PX...",
  "token_expires_at": "2026-03-15T...",
  "status": "active"
{'}'}

Important: The access token is sensitive. Only request it when you need to make an API call. Do not store it client-side.

Delete a Connection

DELETE /apps/{app_id}/orgs/{org_id}/connections/{connection_id}
Authorization: Bearer ADMIN_TOKEN

Token Lifecycle

Auto-Refresh

Mushu automatically manages token expiration:

Lazy refresh: When you request a token via /token, Mushu checks if it expires within 7 days and refreshes it automatically.
Proactive refresh: A daily background job scans for tokens expiring within 14 days and refreshes them.

Connection Status

Status	Meaning	Action
`active`	Token is valid and working	None needed
`refresh_failed`	Token still valid but refresh attempt failed	Will retry on next access
`expired`	Token has expired and cannot be refreshed	Re-authorize via OAuth flow

When a connection's status is expired, the /token endpoint returns 410 Gone. An admin must re-initiate the OAuth flow to reconnect.

FAQ

Who can create org connections?

Only org admins and owners can initiate the OAuth flow and delete connections. All org members can list connections and retrieve tokens.

Can an org have multiple connections to the same service?

Yes. Each OAuth authorization creates a new connection. This is useful when an org manages multiple Facebook ad accounts, for example.

What happens if the external account revokes access?

The next time Mushu tries to refresh or use the token, it will fail. The connection status will be set to expired and an admin will need to re-authorize.

How long do Facebook tokens last?

Mushu exchanges short-lived tokens for long-lived tokens (~60 days). Auto-refresh extends them before expiry. If refresh fails, re-authorize.