Skip to main content

​
Overview

API Secrets provide a secure, permanent way to authenticate with the WaterrAI API. Unlike JWT tokens which expire, API secrets never expire and can be revoked or reactivated as needed. They are ideal for server-to-server communication and automation.
Security: API secrets are hashed using bcrypt and never stored in plain text. The plain secret is only shown once during creation - make sure to save it immediately!

​
Create API Secret

Generate a new API secret for your account. The plain secret is only returned once, so save it immediately.
​
name
string
required
User-friendly name for the API secret (e.g., “Production API Key”, “CI/CD Pipeline”)
curl -X POST https://api.waterrai.com/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!"
  }
}
Important: The plain secret (secret field) is only returned once during creation. If you lose it, you’ll need to create a new API secret. The secret cannot be retrieved later.

​
Get All API Secrets

Retrieve all API secrets for your account. Note that the plain secret is never returned - only the prefix for identification.
​
none
curl -X GET https://api.waterrai.com/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",
      "updated_at": "2024-01-19T20:00:00.000Z"
    },
    {
      "id": 2,
      "name": "Development Key",
      "secret_prefix": "wai_xyz789ab",
      "last_used_at": null,
      "is_active": true,
      "created_at": "2024-01-19T18:00:00.000Z",
      "updated_at": "2024-01-19T18:00:00.000Z"
    }
  ]
}

​
Get API Secret by ID

Retrieve details of a specific API secret.
​
id
integer
required
The API secret ID
curl -X GET https://api.waterrai.com/api-secrets/1 \
  -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",
    "updated_at": "2024-01-19T20:00:00.000Z"
  }
}

​
Revoke API Secret

Deactivate an API secret. Revoked secrets cannot be used for authentication but can be reactivated later.
​
id
integer
required
The API secret ID to revoke
curl -X POST https://api.waterrai.com/api-secrets/1/revoke \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "status": "success",
  "message": "API secret revoked successfully",
  "data": {
    "id": 1,
    "name": "Production API Key",
    "is_active": false
  }
}

​
Reactivate API Secret

Reactivate a previously revoked API secret.
​
id
integer
required
The API secret ID to reactivate
curl -X POST https://api.waterrai.com/api-secrets/1/reactivate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "status": "success",
  "message": "API secret reactivated successfully",
  "data": {
    "id": 1,
    "name": "Production API Key",
    "is_active": true
  }
}

​
Delete API Secret

Permanently delete an API secret. This action cannot be undone.
​
id
integer
required
The API secret ID to delete
curl -X DELETE https://api.waterrai.com/api-secrets/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "status": "success",
  "message": "API secret deleted successfully"
}

​
Using API Secrets

Once you have an API secret, use it exactly like a JWT token in the Authorization header: 
curl -X GET https://api.waterrai.com/personas \
  -H "Authorization: Bearer wai_abc123def456789012345678901234567890123456789012345678901234567890"
API secrets work with all API endpoints and provide the same access as JWT tokens.

​
API Secret Format

  • Prefix: wai_ (WaterrAI identifier)
  • Length: 64 characters total (4 char prefix + 60 char random)
  • Format: wai_[64 hex characters]
  • Example: wai_abc123def456789012345678901234567890123456789012345678901234567890

​
Best Practices

Store Securely

Store API secrets in environment variables or secure secret management systems. Never commit them to version control.

Use Descriptive Names

Give your API secrets descriptive names (e.g., “Production”, “Staging”, “CI/CD”) to easily identify their purpose.

Rotate Regularly

Periodically rotate your API secrets, especially if they may have been compromised.

Revoke Unused Keys

Revoke API secrets that are no longer needed instead of deleting them, in case you need to reactivate them later.
Multiple Secrets: You can create multiple API secrets for different environments or services. Each secret is independent and can be managed separately.