Intermediate6 min

OAuth Connections

OAuth provides secure access to external services without sharing passwords. Users authorize access through the service's login page.

How OAuth Works

The Flow

  1. You click Connect on a service
  2. Redirected to service's auth page
  3. Log in and approve permissions
  4. Redirected back with access token
  5. Token stored securely

Token Management

  • Access Token: Used for API calls
  • Refresh Token: Gets new access tokens
  • Tokens refresh automatically

Connecting OAuth Services

Built-in Integrations

  1. Go to Plugins
  2. Find the service (Slack, Google, etc.)
  3. Click Connect
  4. Authorize in popup
  5. Connection saved

Custom OAuth

For custom API imports:

  1. Import or create the API
  2. Go to Authentication
  3. Select OAuth 2.0
  4. Enter OAuth details:
    • Authorization URL
    • Token URL
    • Client ID
    • Client Secret
    • Scopes

OAuth Configuration

Required Settings

| Setting | Description | |---------|-------------| | Auth URL | Where users authorize | | Token URL | Where tokens are exchanged | | Client ID | Your app identifier | | Client Secret | Your app secret |

Scopes

Scopes define what access you're requesting:

read:user
write:messages
admin:org

Request only scopes you need.

Redirect URI

Use our callback URL:

https://api.specway.com/oauth/callback

Register this in the external service's developer console.

Managing Connections

View Status

  1. Go to Settings > Integrations
  2. See connection status
  3. Green = active, Red = needs attention

Refresh Connection

If a connection fails:

  1. Find the connection
  2. Click Refresh
  3. Re-authorize if prompted

Disconnect

  1. Find the connection
  2. Click Disconnect
  3. Confirm removal

Note: Disconnect from the external service too for full revocation.

Team Connections

Personal vs Shared

Personal: Only you can use Shared: Team members can use in their workflows

Creating Shared Connections

  1. Connect the service
  2. Go to connection settings
  3. Enable Share with team
  4. Set permission level

Using Shared Connections

Team members see shared connections:

  1. In workflow, add action
  2. Select the integration
  3. Choose shared connection
  4. No additional auth needed

Security

Token Storage

  • Encrypted at rest
  • Never logged
  • Secure vault storage

Scope Minimization

Request minimum necessary scopes:

  • Read-only when possible
  • Specific resources only
  • Avoid admin scopes

Audit

Track connection usage:

  1. Go to Settings > Audit Log
  2. Filter by integration
  3. See all access events

Troubleshooting

Token Expired

Tokens auto-refresh, but if issues:

  1. Click Refresh on connection
  2. Re-authorize if needed

Insufficient Permissions

Error indicates missing scopes:

  1. Disconnect
  2. Reconnect with additional scopes
  3. Approve new permissions

Connection Failed

Common causes:

  • Popup blocked
  • Service down
  • Invalid credentials

See Troubleshooting Auth.

Next Steps

Tags

integrationsoauthsecurity