MasterclassADVANCED AUTH

Unified OAuth 2.0

Stop building login flows. Cortex handles the handshakes, redirects, and token lifecycle, delivering a clean access token directly to your tool.

The "OAuth in Chat" Problem

Building OAuth for a WhatsApp bot is notoriously difficult. Where do you redirect the user? How do you map a phone number to a Google account securely? How do you handle refresh tokens in a stateless webhook?

Cortex solves this by acting as a Managed OAuth Proxy. We handle the entire User Experience on the phone, and your plugin server remains 100% stateless.

1

Declare User Auth

Update your manifest to request user-level permissions.

Add the auth block to your manifest.json. You must specify the standard OAuth 2.0 endpoints for your provider (Google, GitHub, HubSpot, etc.).

Tip: Always request offline_access or equivalent scopes if you need the token to be refreshed automatically while the user is away.
json
{
  "slug": "GMAIL_SYNC",
  "auth": {
    "type": "oauth2",
    "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
    "tokenUrl": "https://oauth2.googleapis.com/token",
    "scope": [
      "https://www.googleapis.com/auth/gmail.readonly",
      "https://www.googleapis.com/auth/gmail.send"
    ]
  }
}
2

Configure Secrets

Securely link your App Credentials via the Developer Dashboard.

  • Go to Developer Settings > Plugins.
  • Select your plugin and click Configure OAuth.
  • Enter your Client ID and Client Secret.
REDIRECT URI:
https://app.kasilabs.com/api/oauth/callback
Dashboard UI Mock
3

Receive the Token

Your tool receives a valid token in every authenticated request.

When the AI triggers your tool, Cortex checks if a token exists for that user. If not, the bot automatically sends an "Authorize" button to the user's phone. Once they approve, your tool is called with the token.

javascript
app.post("/tools/send-email", async (req, res) => {
  // 1. Get the Context from the request body
  const { context } = req.body;
  
  // 2. Extract the User's Access Token
  // Cortex handles all the OAuth handshakes and token refreshes.
  const accessToken = context.userAccessToken;

  if (!accessToken) {
    // This tool is being called without a user session.
    // Return 401 and Cortex will prompt the user to login on WhatsApp.
    return res.status(401).json({ 
       error: "Authentication required. Please sign in to Google." 
    });
  }

  // 3. Use the token to call the upstream API
  try {
    const result = await fetch("https://gmail.googleapis.com/gmail/v1/users/me/messages/send", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(req.body.input)
    });
    
    const data = await result.json();
    res.json(data);
  } catch (err) {
    res.status(500).json({ error: "Failed to send email" });
  }
});

Defense in Depth

Even with OAuth, you should still verify the Cortex Signature (HMAC) in the Authorization header to ensure the request actually came from our gateway.

User Experience

The "Auth Trap" is automatic. If you return a 401 Unauthorized with an error message, Cortex will transparently handle the redirect on WhatsApp.