Authentication

Using MCP instead? The MCP server uses the same wai_ API keys documented below — send them as Authorization: Bearer wai_... on every request. Browser-based OAuth is on the roadmap but has not shipped.

Get your API key

The fastest way to get an API key is from the WaterrAI dashboard.

Go to waterr.ai and sign in with Google, Microsoft, or LinkedIn.

Open API Keys

Click your profile, open Settings, then choose API Keys from the sidebar — or go directly to waterr.ai/settings?tab=api-keys.

Create a key

Click Create API Key, give it a recognizable name (e.g. Production, CI/CD), and copy the key when it’s shown. You’ll only see the full key once — store it somewhere safe.

Security: Keys are hashed with bcrypt and never stored in plain text. The plain key is only shown once during creation — if you lose it, create a new one.

Using your API key

Send the key in the Authorization header on any API request:

curl -X GET https://api.waterr.ai/v1/personas \
  -H "Authorization: Bearer wai_abc123def456..."

Key format

Prefix: wai_ (WaterrAI identifier)
Length: 68 characters (4 char prefix + 64 hex characters)
Format: wai_[64 hex characters]

Managing keys

You can revoke, reactivate, or delete keys at any time from Settings → API Keys.

Revoke — disables the key. Existing requests using it will start failing. Reversible.
Reactivate — re-enables a revoked key. The same secret resumes working.
Delete — permanently removes the key. Cannot be undone — use revoke instead if you might want it back.

Best practices

Store securely

Keep keys in environment variables or a secret manager. Never commit them to version control or share them in chat.

One key per use

Create separate keys for each environment or service (e.g. Production, Staging, GitHub Actions) so you can revoke one without breaking the rest.

Rotate regularly

Periodically create a new key, switch your services over, and revoke the old one — especially if a key may have been exposed.

Revoke, don't delete

Prefer revoking keys you don’t need. You can reactivate a revoked key; you can’t recover a deleted one.

REST API reference

The same operations are available over REST if you’re automating key management (for example, provisioning keys from CI). All /api-secrets endpoints require a logged-in user JWT.

Create API key

string

required

A recognizable name for the key (e.g. “Production API Key”, “CI/CD Pipeline”).

curl -X POST https://api.waterr.ai/v1/api-secrets \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production API Key" }'

{
  "status": "success",
  "message": "API secret created successfully",
  "data": {
    "id": 1,
    "name": "Production API Key",
    "secret": "wai_abc123def456789012345678901234567890123456789012345678901234567890",
    "secret_prefix": "wai_abc123de",
    "created_at": "2024-01-19T19:37:07.000Z",
    "warning": "Save this secret now. You won't be able to see it again!"
  }
}

The plain secret is only returned once. If you lose it, create a new key.

List API keys

Returns metadata for every key on your account. The plain secret is never returned — only the prefix.

curl -X GET https://api.waterr.ai/v1/api-secrets \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Production API Key",
      "secret_prefix": "wai_abc123de",
      "last_used_at": "2024-01-19T20:00:00.000Z",
      "is_active": true,
      "created_at": "2024-01-19T19:37:07.000Z"
    }
  ]
}

Revoke API key

Disable a key. Revoked keys can be reactivated later.

curl -X POST https://api.waterr.ai/v1/api-secrets/1/revoke \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Reactivate API key

curl -X POST https://api.waterr.ai/v1/api-secrets/1/reactivate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Delete API key

Permanent — cannot be undone.

curl -X DELETE https://api.waterr.ai/v1/api-secrets/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Getting Started

Meetings

Personas

Scenarios

Embed Scenario

Post-Meeting Data

Goals

Avatars

Voices

Tools

Users

Guides

Integrations

Agent Skills

Get your API key

Using your API key

Key format

Managing keys

Best practices

Store securely

One key per use

Rotate regularly

Revoke, don't delete

REST API reference

Create API key

List API keys

Revoke API key

Reactivate API key

Delete API key

​Get your API key

​Using your API key

​Key format

​Managing keys

​Best practices

Store securely

One key per use

Rotate regularly

Revoke, don't delete

​REST API reference

​Create API key

​List API keys

​Revoke API key

​Reactivate API key

​Delete API key

Get your API key

Using your API key

Key format

Managing keys

Best practices

REST API reference

Create API key

List API keys

Revoke API key

Reactivate API key

Delete API key