Troubleshooting Authentication

Common authentication issues and how to fix them.

OAuth Issues

"Authorization Failed"

Causes:

• Popup was blocked
• User denied access
• Invalid OAuth configuration

Solutions:

1. Allow popups for our domain
2. Try connecting again
3. Approve all requested permissions
4. Check OAuth credentials are correct

"Token Expired"

Causes:

• Refresh token invalid
• User revoked access
• Service requires re-auth

Solutions:

1. Click Refresh on the connection
2. If that fails, disconnect and reconnect
3. Check you haven't revoked access in the external service

"Insufficient Permissions"

Causes:

• Missing required scopes
• User doesn't have access
• Organization restrictions

Solutions:

1. Disconnect the integration
2. Reconnect and approve additional scopes
3. Contact your organization admin

"Redirect URI Mismatch"

Causes:

• Wrong callback URL configured
• Missing redirect URI in app settings

Solutions:

1. Go to external service's developer console
2. Add our redirect URI:

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

3. Save and retry

API Key Issues

"Invalid API Key"

Causes:

• Typo in key
• Key was revoked
• Key expired

Solutions:

1. Copy key again from source
2. Check key status in external service
3. Generate new key if needed

"Unauthorized"

Causes:

• Key location wrong (header vs query)
• Wrong header name
• Missing key prefix

Solutions:

1. Check API documentation for correct format
2. Verify header name matches
3. Add prefix if required (e.g., Bearer )

"Rate Limited"

Causes:

• Too many requests
• Key has low limits

Solutions:

1. Add delays in workflows
2. Reduce concurrent executions
3. Upgrade API plan for higher limits

Connection Errors

"Connection Refused"

Causes:

• Service is down
• Firewall blocking
• Wrong URL

Solutions:

1. Check service status page
2. Verify URL is correct
3. Test URL in browser
4. Check if IP allowlisting needed

"Timeout"

Causes:

• Slow API response
• Network issues
• Large payload

Solutions:

1. Increase timeout setting
2. Check network connectivity
3. Reduce request size
4. Contact API provider

"SSL Certificate Error"

Causes:

• Expired certificate
• Self-signed certificate
• Certificate mismatch

Solutions:

1. Report to API provider
2. Check if they have a different URL
3. For internal APIs, configure certificate

Service-Specific Issues

Slack

"missing_scope"

• Reconnect with additional permissions
• Your workspace may require admin approval

"channel_not_found"

• Bot needs to be invited to channel
• Check channel ID is correct

Google

"Access blocked"

• App may need verification
• Check Google security settings
• Try with different Google account

"Quota exceeded"

• Check Google Cloud quotas
• Reduce API usage
• Request quota increase

GitHub

"Bad credentials"

• Token may have expired
• Check token permissions
• Generate new personal access token

"Resource not accessible"

• Need additional permissions
• Check repository access
• Verify organization access

Debugging Steps

1. Check Credential Status

1. Go to Settings > Credentials
2. Find the credential
3. Check status indicator
4. View error details

2. Test the Connection

1. Click Test on the credential
2. View the response
3. Check for error messages

3. Review Workflow Logs

1. Open failed workflow execution
2. Find the failed node
3. View error details
4. Check request/response

4. Check External Service

1. Log into external service
2. Verify credentials are valid
3. Check for service issues
4. Review access permissions

Getting Help

If issues persist:

1. Gather information:
   • Error message
   • Service name
   • Steps to reproduce
2. Check support articles
3. Contact support with details

Next Steps

• OAuth Connections - Setup guide
• API Key Management - Managing keys
• Credential Management - Overview