Authentication — Cognest.ai Docs

API Keys#

Every Cognest project requires an API key to authenticate with the Cognest cloud services. You can generate keys from the dashboard or via the CLI.

terminal

# Generate a new API key
cognest auth login

# Verify your authentication
cognest auth whoami
# → Authenticated as: team@company.com (org: my-org)

Keep your keys safe

Never commit API keys to source control. Use environment variables or a secrets manager instead. See the Environment Variables guide for best practices.

Environment Variables#

Store your API key and integration credentials as environment variables. Cognest automatically reads from .env files in your project root.

.env

# .env
COGNEST_API_KEY=cn_live_sk_a1b2c3d4e5f6...
COGNEST_ORG_ID=org_my-organization

# Integration credentials
WHATSAPP_PHONE_ID=1234567890
WHATSAPP_ACCESS_TOKEN=EAAx...
GMAIL_CLIENT_ID=123456789-abc.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=GOCSPX-...

OAuth 2.0 Integrations#

Some integrations (Gmail, Google Calendar, Google Drive, Notion) use OAuth 2.0 for authentication. Cognest provides a built-in OAuth flow handler.

auth.ts

import { Cognest } from '@cognest/sdk'

const cognest = new Cognest()

// Start OAuth flow for Gmail
const authUrl = await cognest.auth.getOAuthUrl('gmail', {
  redirectUri: 'http://localhost:3000/callback',
  scopes: ['gmail.readonly', 'gmail.send'],
})

// Exchange code for tokens (in your callback handler)
const tokens = await cognest.auth.exchangeCode('gmail', {
  code: req.query.code,
  redirectUri: 'http://localhost:3000/callback',
})

// Tokens are automatically stored and refreshed

Token Management#

Cognest handles token refresh automatically for OAuth integrations. Tokens are encrypted at rest and stored in your project's secure credential store.

Method	Description
cognest.auth.getTokens(integration)	Retrieve current tokens for an integration
cognest.auth.revokeTokens(integration)	Revoke and delete stored tokens
cognest.auth.refreshTokens(integration)	Force a token refresh
cognest.auth.isAuthenticated(integration)	Check if valid tokens exist

Webhook Verification#

For integrations that use webhooks (WhatsApp, Telegram, Slack, Discord), Cognest automatically verifies incoming webhook signatures to prevent unauthorized access.

cognest.config.yaml

# cognest.config.yaml
integrations:
  whatsapp:
    enabled: true
    credentials:
      phone_number_id: ${WHATSAPP_PHONE_ID}
      access_token: ${WHATSAPP_ACCESS_TOKEN}
    settings:
      webhook_verify_token: ${WEBHOOK_VERIFY_TOKEN}
      # Cognest verifies all incoming webhook payloads
      # against Meta's signature headers automatically

Service Accounts#

For production deployments, we recommend using service accounts instead of personal OAuth tokens. Service accounts provide non-expiring, scoped access.

terminal

# Create a service account
cognest auth create-service-account --name "production-bot" --scopes "integrations:read,integrations:write,skills:execute"

# Output:
# Service Account ID: sa_prod_a1b2c3d4
# Service Account Key: cn_sa_sk_e5f6g7h8...
# Store this key securely — it cannot be retrieved again.