Skip to main content

​
Authentication

thinnestAI uses API keys for programmatic access and Auth0 for dashboard authentication. This guide covers how to authenticate your API requests, set up OAuth integrations, and secure your endpoints.

​
API Key Authentication

Every API request to thinnestAI must include a valid API key. API keys are scoped to your account and have full access to all your resources.

​
Getting Your API Key

  1. Sign in to the thinnestAI Dashboard.
  2. Go to Settings > API Keys.
  3. Click Generate API Key.
  4. Copy and store the key securely. It will only be shown once.

​
Using Your API Key

Include the key in the Authorization header of every request: 
curl https://api.thinnest.ai/agents \
  -H "Authorization: Bearer your-api-key-here"
Or set it as an environment variable: 
THINNESTAI_API_KEY=your-api-key-here
Then reference it in your requests: 
curl https://api.thinnest.ai/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"

​
API Key Best Practices

  • Never commit API keys to source control. Use environment variables or a secrets manager.
  • Rotate keys regularly. You can generate a new key and revoke the old one from the dashboard.
  • Use separate keys for development and production. This limits the blast radius if a key is compromised.
  • Monitor usage. Check the dashboard for unexpected API activity.

​
Revoking a Key

  1. Go to Settings > API Keys.
  2. Find the key you want to revoke.
  3. Click Revoke. The key is immediately invalidated.
Revoking a key does not affect your agents, phone numbers, or any other resources. It only stops future API requests using that key.

​
Dashboard Authentication (Auth0)

The thinnestAI Dashboard uses Auth0 for user authentication. When you sign up or log in at app.thinnest.ai, you’re authenticating through Auth0.

​
Supported Login Methods

  • Email + Password — Standard email/password registration
  • Google OAuth — Sign in with your Google account
  • GitHub OAuth — Sign in with your GitHub account

​
Team Access

If you’re working with a team, you can invite members from Settings > Team:
  1. Click Invite Member.
  2. Enter their email address.
  3. Choose a role:
    • Admin — Full access to all settings, billing, and agents
    • Editor — Can create and modify agents, but no billing access
    • Viewer — Read-only access to agents and call logs
The invited user receives an email and can sign up or sign in to access your workspace.

​
OAuth Integrations

Some agent tools require OAuth authentication to access third-party services on behalf of your users. thinnestAI handles the OAuth flow for you.

​
Google OAuth (Gmail, Calendar, Sheets)

To let your agents send emails, manage calendars, or access spreadsheets, you need to connect a Google account:
  1. Go to your agent’s Tools tab.
  2. Click Add Tool and select a Google tool (Gmail, Calendar, or Sheets).
  3. Click Connect Google Account.
  4. You’ll be redirected to Google’s OAuth consent screen.
  5. Grant the requested permissions.
  6. You’re redirected back to thinnestAI with the connection active.
Your agent can now use Google tools on behalf of the connected account.

​
Required Google OAuth Scopes

ToolScopes
Gmailgmail.send, gmail.readonly
Google Calendarcalendar.events, calendar.readonly
Google Sheetsspreadsheets, spreadsheets.readonly

​
Disconnecting OAuth

To disconnect a Google account:
  1. Go to Settings > Integrations.
  2. Find the Google connection.
  3. Click Disconnect.
This revokes thinnestAI’s access to the connected Google account. Agents using Google tools will stop working until a new account is connected.

​
Webhook Authentication

If you’re receiving webhooks from thinnestAI (e.g., call events, campaign updates), you can verify the authenticity of incoming requests.

​
Webhook Signatures

Every webhook request from thinnestAI includes a signature header: 
X-ThinnestAI-Signature: sha256=abc123...
Verify it using your webhook secret: 
import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

​
Getting Your Webhook Secret

  1. Go to Settings > Webhooks.
  2. Create or edit a webhook endpoint.
  3. Copy the Signing Secret.

​
Embedded Chat Widget Authentication

When embedding the chat widget on your website, the agent ID is public. To restrict who can use the widget, enable Allowed Origins:
  1. Go to your agent’s Settings > Embed.
  2. Add your website domain(s) to Allowed Origins: 
    https://www.yoursite.com
https://app.yoursite.com
  3. Save. The widget will only load on pages served from these domains.

​
Authenticated Widget Sessions

For logged-in users on your website, you can pass user identity to the widget so the agent knows who it’s talking to: 
<script
  src="https://app.thinnest.ai/embed.js"
  data-agent-id="agent_abc123"
  data-user-id="user_12345"
  data-user-name="Jane Smith"
  data-user-email="jane@example.com"
  data-user-hash="hmac-signature-here"
  async
></script>
The data-user-hash is an HMAC-SHA256 signature of the user ID, signed with your webhook secret. This prevents users from impersonating others: 
import hmac
import hashlib

user_hash = hmac.new(
    webhook_secret.encode(),
    user_id.encode(),
    hashlib.sha256
).hexdigest()

​
API Rate Limits

To protect the platform, API requests are rate-limited per account:
EndpointLimit
Agent CRUD60 requests/minute
Chat/Conversation120 requests/minute
Call triggers30 requests/minute
Knowledge upload20 requests/minute
All other endpoints60 requests/minute
When you exceed a rate limit, the API returns a 429 Too Many Requests response with a Retry-After header: 
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 30 seconds.",
  "retry_after": 30
}

​
Security Recommendations

  1. Use HTTPS for all API calls. The API rejects plain HTTP requests.
  2. Store keys in environment variables or a secrets manager — never hardcode them.
  3. Restrict embed widget origins to your own domains.
  4. Verify webhook signatures to ensure requests are genuinely from thinnestAI.
  5. Rotate API keys periodically, especially if team members leave.
  6. Use the principle of least privilege when assigning team roles.
  7. Monitor your usage dashboard for unexpected activity.

​
Error Responses

Status CodeMeaning
401 UnauthorizedMissing or invalid API key
403 ForbiddenValid key but insufficient permissions
429 Too Many RequestsRate limit exceeded
If you receive a 401, double-check that:
  • The API key is included in the Authorization header
  • The key hasn’t been revoked
  • The header format is Bearer your-key-here (note the space after “Bearer”)