Testing & Development

This guide covers setting up a local development environment for testing Connected Accounts integrations, including OAuth flows, provider-specific setup, and testing strategies.

Local Development Setup

OAuth Callback URLs

OAuth providers require a callback URL that's accessible during the authorization flow. Supyagent's callback handler is at:

https://app.supyagent.com/api/v1/connect/callback

Since Supyagent hosts the OAuth callback, your local development only needs to handle the redirect URL — where Supyagent sends the user after the OAuth flow completes. This can be localhost:

http://localhost:3000/integrations/callback

Step-by-Step Local Testing

curl -X POST https://app.supyagent.com/api/v1/accounts \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "test-user-1",
    "display_name": "Test User",
    "metadata": { "environment": "development" }
  }'

curl -X POST https://app.supyagent.com/api/v1/accounts/ACCOUNT_UUID/connect \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "redirect_url": "http://localhost:3000/callback"
  }'

http://localhost:3000/callback?status=success&provider=google&account_id=test-user-1

curl https://app.supyagent.com/api/v1/accounts/ACCOUNT_UUID/integrations \
  -H "Authorization: Bearer sk_live_your_key_here"

curl https://app.supyagent.com/api/v1/google/gmail/messages \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "X-Account-Id: test-user-1"

Testing Without a Frontend

You don't need a running web application to test the full Connected Accounts flow. Here are two approaches:

Minimal HTTP Server

Use a one-liner to catch the OAuth callback:

# Start a minimal server to capture the callback
python3 -c "
from http.server import HTTPServer, BaseHTTPRequestHandler

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        print(f'\nCallback received: {self.path}')
        self.send_response(200)
        self.end_headers()
        self.wfile.write(b'OAuth callback received! Check your terminal.')

HTTPServer(('localhost', 3000), Handler).serve_forever()
"

# Start a minimal server to capture the callback
node -e "
require('http').createServer((req, res) => {
  console.log('\nCallback received:', req.url);
  res.end('OAuth callback received! Check your terminal.');
}).listen(3000, () => console.log('Listening on http://localhost:3000'));
"

Then create a connect session with redirect_url: "http://localhost:3000/callback" and open the connect_url in your browser.

Using ngrok for Remote Callbacks

If your development environment can't receive localhost callbacks (e.g., testing from a mobile device or remote server):

# Start ngrok tunnel
ngrok http 3000

# Use the ngrok URL as your redirect_url
# e.g., "https://abc123.ngrok.io/callback"

Provider-Specific Setup Notes

Google

• Use a test Google account (not your production account) during development
• Google may show an "unverified app" warning — click "Advanced > Go to app" to proceed
• Google tokens expire after 1 hour and are automatically refreshed by Supyagent
• If testing Gmail, note that the test account must have Gmail enabled

Slack

• Create a dedicated Slack workspace for testing
• Slack tokens don't expire, but can be revoked from the workspace settings
• Bot tokens give access to channels the bot has been invited to

GitHub

• Create a personal test account or use your existing account
• GitHub tokens expire after 8 hours and are automatically refreshed
• Fine-grained tokens may limit which repositories are accessible

Microsoft

• Use a personal Microsoft account or a test tenant
• Microsoft tokens expire after 1 hour and are automatically refreshed
• Admin consent may be required for organizational accounts

Debugging OAuth Sessions

If an OAuth flow isn't completing, use the session status endpoint to diagnose:

# Check session status
curl https://app.supyagent.com/api/v1/accounts/ACCOUNT_UUID/connect/SESSION_UUID \
  -H "Authorization: Bearer sk_live_your_key_here" | jq

Common issues:

• Session stuck on pending — The user didn't complete the OAuth consent, or the callback URL was unreachable
• Session expired — Create a new session. The 30-minute window starts when the session is created, not when the user opens the URL
• Session failed — Check the error field in the response for details

Test Account Cleanup

After testing, clean up test accounts to avoid clutter:

# Delete a test account (cascades to all integrations)
curl -X DELETE https://app.supyagent.com/api/v1/accounts/ACCOUNT_UUID \
  -H "Authorization: Bearer sk_live_your_key_here"

You can also use metadata to identify test accounts for batch cleanup:

# Create accounts with test metadata
curl -X POST https://app.supyagent.com/api/v1/accounts \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "test-user-cleanup",
    "metadata": { "environment": "test", "created_by": "integration-tests" }
  }'

Then list and filter accounts by metadata in your cleanup scripts.

Environment Checklist

Before going to production, verify:

• API key is stored securely (environment variable, not committed to code)
• redirect_url points to your production domain (not localhost)
• Error handling covers all OAuth error codes
• Rate limit retry logic is implemented
• Integration status is checked before making provider calls
• Token errors trigger a re-authorization flow for the user