Authentication & OAuth

Every API request must be authenticated. Choose between workspace API keys for backend integrations or OAuth flows when you need delegated user access.

Workspace API Keys

Workspace Owners and Admins can create API keys from Workspace Settings → Integrations.

1. Click Create API Key.
2. Provide a name (e.g., "BI Dashboard").
3. Select scopes: analytics.read, posts.write, media.read, reviews.read, etc.
4. Copy the generated key—this is the only time it is shown.

Request Header

Authorization: Bearer <workspace_api_key>
X-Altyaa-Workspace: <workspace_id>

Keys inherit Row Level Security based on the workspace they originate from. Rotate keys every 90 days or when teammates change.

OAuth Authorization Code Flow

Use OAuth when building apps that act on behalf of a user. The flow mirrors standard OAuth 2.0:

1. Authorize: Redirect the user to https://app.altyaa.com/oauth/authorize with client ID, redirect URI, requested scopes, and state.
2. Consent: The user reviews requested access and approves or denies.
3. Callback: Altyaa redirects to your redirect_uri with an authorization code.
4. Token Exchange: POST the authorization code to /oauth/token with your client secret to receive access and refresh tokens.
5. API Calls: Use the access token in the Authorization header.
6. Refresh: When the access token expires, exchange the refresh token for a new pair.

Access tokens last 1 hour; refresh tokens last 60 days. Refresh tokens are one-time use—store new tokens promptly.

Token Storage & Security

• Encrypt tokens at rest. We recommend using a secrets manager or KMS-backed storage.
• Never embed access tokens in client-side code.
• Store the associated workspace ID and scopes with each token to audit access quickly.
• Revoke tokens from Workspace Settings → Integrations if suspicious activity occurs.

Social Platform Tokens

When connecting social accounts, Altyaa handles OAuth with Facebook, Instagram, TikTok, and Google Business Profile on your behalf. Tokens are stored encrypted in Supabase and refreshed automatically:

• Meta (Facebook/Instagram): Short-lived tokens are exchanged for long-lived page tokens every 7 days.
• Google Business Profile: Refresh tokens are rotated every 30 days; hourly health checks detect revoked access.
• TikTok: Business tokens expire every 30 days; Altyaa renews them proactively 3 days before expiry.

Review token status in Reputation Command Center → Connections. Re-authenticate if a token shows as expired.

Handling Redirect Errors

• Validate the state parameter to prevent CSRF.
• Handle error query parameters (access_denied, invalid_scope) gracefully and prompt users with next steps.
• Use the /oauth/token/introspect endpoint to confirm token validity if you suspect issues.

For webhook signature verification, read Webhooks & Events. For rate limits applied to authenticated calls, see Rate Limits & Quotas.