Creating a Connected App takes minutes; configuring it correctly takes thought. The OAuth flow, scopes, callback URLs, IP policies, and session policies all need deliberate choices that match the integration's actual needs. Build in sandbox first, validate every flow path, then promote to production with the right pre-authorization policy.
- Identify the integration use case and OAuth flow
User-facing web app: web server flow. Headless server integration: JWT bearer flow. Mobile or SPA: user-agent flow with PKCE. Service account without user: client credentials flow. The flow choice constrains every other configuration decision.
- Create the Connected App
Setup > App Manager > New Connected App. Enter the basic information (name, API name, contact email, logo). Check Enable OAuth Settings and configure the OAuth flow specifics.
- Set callback URLs
Add the URLs the external app uses for OAuth redirects. Web server flow needs at least one. Multiple callback URLs are supported for dev/stage/prod environments. The URLs must match exactly during the OAuth handshake or the platform rejects the request.
- Pick OAuth scopes
Select the minimum scopes the integration needs. api for REST/SOAP calls. refresh_token for offline access. openid for identity claims. full only when the integration truly needs everything. Avoid full as a habit because it grants more than most integrations actually need.
- Configure certificates if using JWT bearer
Upload the X.509 public certificate that matches the private key the external system will use to sign JWTs. The platform validates JWTs against this certificate during the bearer flow.
- Set permitted users and IP relaxation
Permitted Users: Admin approved users are pre-authorized (recommended for production). All users may self-authorize for low-risk dev tools only. IP Relaxation: Enforce IP restrictions (recommended); relax only when the integration runs from cloud hosts outside the trusted IP range.
- Save and capture the Consumer Key and Secret
Save the Connected App. The platform generates the Consumer Key and Consumer Secret. Store them in a secrets manager (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault). Never embed in source code or client-side bundles.
- Assign permitted profiles or permission sets
Manage Profiles or Manage Permission Sets on the Connected App detail page. Pre-approve the user populations that can use the integration. Without this, users cannot authenticate even with valid credentials.
Web server, JWT bearer, user-agent, device, or client credentials. Drives every other configuration choice on the Connected App.
Controls what the access token can do. api, refresh_token, openid, full, custom_permissions, web. Pick the minimum set the integration needs.
Admin approved (pre-authorized profiles/permission sets) versus All users may self-authorize. Admin approved is the recommended production default.
- The Consumer Secret is sensitive. Never embed in mobile app bundles or single-page apps; use PKCE instead. For server integrations, store in a secrets manager and rotate periodically.
- Callback URLs must match exactly during the OAuth handshake. Trailing slashes, case differences, and protocol mismatches (http versus https) all cause OAuth errors that look mysterious to debug.
- Asking for the full scope is broader than most integrations need. Stick to api, refresh_token, and openid for typical integrations. full grants administrative access and increases blast radius if credentials leak.
- IP Relaxation set to Enforce blocks cloud-hosted integrations whose source IPs are not in the trusted ranges. Relax only when the integration genuinely needs it, and pair with high-assurance session requirements.
- Revoking a Connected App invalidates all outstanding tokens immediately. Coordinate with integration owners before revoking because dependent systems lose access without warning.