Admin Endpoints

These endpoints require a **Firebase ID Token** and the user must have `role: "admin"` in their Firestore profile.

List API Keys

Retrieve all API keys across all clients.

GET /api/admin/apikeys

Auth: Firebase ID Token + Admin role

Response:

[
  {
    "id": "doc-id",
    "userId": "client-uid",
    "clientName": "Client Name",
    "name": "Production Key",
    "maskedKey": "whatapi_live_***abcd",
    "status": "active",
    "createdAt": "2026-06-01T00:00:00.000Z",
    "expiresAt": null,
    "scopes": [
      "send_text",
      "send_media",
      "send_bulk"
    ],
    "rate_limit": 1000,
    "plan": "growth",
    "api_calls": 42
  }
]

Note: The `rawKey` field is **stripped** from admin responses for security.

Create API Key

Generate a new API key for a client.

POST /api/admin/apikeys

Auth: Firebase ID Token + Admin role

Request Body:

ParameterTypeRequiredDescription

userIdstringYesThe client user to assign this key to

namestringYesHuman-readable name for the key

expiresAtstringNoISO date string for key expiration

scopesarrayNoPermissions (default: `["send_text","send_media","send_bulk"]`)

Response:

{
  "id": "new-doc-id",
  "userId": "client-uid",
  "clientName": "Client Name",
  "name": "Production Key",
  "maskedKey": "whatapi_live_***abcd",
  "rawKey": "whatapi_live_a1b2c3d4...",
  "status": "active",
  "createdAt": "2026-07-02T00:00:00.000Z",
  "expiresAt": null,
  "scopes": [
    "send_text",
    "send_media",
    "send_bulk"
  ]
}

⚠️ The `rawKey` is returned **only on creation**. Save it immediately as it cannot be retrieved later.

Update API Key

Modify an existing API key's name or status.

PATCH /api/admin/apikeys

Auth: Firebase ID Token + Admin role

Request Body:

ParameterTypeRequiredDescription

idstringYesAPI key document ID

namestringNoUpdated name

statusstringNoactive or `revoked`

Response:

{
  "success": true
}

Delete API Key

Permanently remove an API key.

DELETE /api/admin/apikeys?id=<doc-id>

Auth: Firebase ID Token + Admin role

Query Parameters:

ParameterTypeRequiredDescription

idstringYesAPI key document ID to delete

Response:

{
  "success": true
}

Validate API Key

Check whether an API key is valid without requiring authentication.

POST /api/admin/apikeys/validate

Auth: None (public)

Request Body:

ParameterTypeRequiredDescription

rawKeystringYesThe full API key string to validate

Response (valid):

{
  "valid": true,
  "id": "doc-id",
  "name": "Production Key",
  "userId": "client-uid",
  "clientName": "Client Name",
  "createdAt": "2026-06-01T00:00:00.000Z",
  "expiresAt": null,
  "scopes": [
    "send_text",
    "send_media",
    "send_bulk"
  ]
}

Response (invalid):

{
  "valid": false,
  "error": "Invalid API key"
}

List Sessions

Retrieve all WhatsApp sessions with their assignment status.

GET /api/admin/sessions

Auth: None

Response:

[
  {
    "id": "session-uuid",
    "name": "Main WhatsApp",
    "status": "CONNECTED",
    "phone": "923001234567",
    "assignedTo": "client-uid-or-null",
    "clientName": "Client Name or null",
    "createdAt": "2026-06-01T00:00:00.000Z",
    "lastActivity": "2026-07-02T12:00:00.000Z"
  }
]

Create Session

Create a new WhatsApp session on OpenWA.

POST /api/admin/sessions/create

Auth: None

Request Body:

ParameterTypeRequiredDescription

sessionNamestringYesName for the new WhatsApp session

assignToUserIdstringNoUser ID to immediately assign this session to

Response:

{
  "success": true,
  "session": {
    "id": "session-uuid",
    "name": "Main WhatsApp",
    "status": "created"
  }
}

Assign Session

Assign an existing WhatsApp session to a user.

POST /api/admin/sessions/assign

Auth: None

Request Body:

ParameterTypeRequiredDescription

sessionIdstringYesSession ID to assign

userIdstringYesUser ID to assign the session to

Response:

{
  "success": true
}