Operators

Operators run the engage-ai deployment itself. They provision organizations for customers and help people who have lost their credentials. Everything here is under /admin/* and needs an administrator token (eng_adm_…). Tenant tokens get 401 on these routes, and administrator tokens get 401 everywhere else. An operator can create a tenant but cannot read its messages.

If you are integrating as a business, you do not need this page.

The first administrator

A new deployment has no administrators. The ADMIN_API_KEY from the server's configuration creates the first one, and only the first one:

curl -X POST https://api.getengageai.app/admin/users \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "alice@ops.example", "name": "Alice" }'

The response includes a temporaryPassword, shown once. After that, ADMIN_API_KEY is refused for creating administrators, so disabling an operator really does remove their access.

Signing in

curl -X POST https://api.getengageai.app/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "alice@ops.example", "password": "…" }'

{
  "accessToken": "eng_adm_a595150c…",
  "expiresAt": "2026-10-16T21:30:00.000Z",
  "mustChangePassword": true,
  "admin": { "id": "…", "email": "alice@ops.example", "name": "Alice" }
}

Sessions last 12 hours by default; read expiresAt. Change your password with POST /admin/auth/password, which signs out all your admin sessions. Actions taken with a session are recorded against your name in the audit log.

Managing administrators

# Add an operator (signed in as one)
curl -X POST https://api.getengageai.app/admin/users -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" -d '{ "email": "bob@ops.example", "name": "Bob" }'

# List operators
curl https://api.getengageai.app/admin/users -H "Authorization: Bearer $ADMIN_TOKEN"

# Disable one. Their sessions end immediately.
curl -X POST https://api.getengageai.app/admin/users/$ADMIN_ID/disabled -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" -d '{ "disabled": true }'

Accounts are disabled, never deleted, so the audit log keeps showing who did what. You cannot disable your own account (409).

Provisioning an organization

When a business should not sign itself up, create it for them:

curl -X POST https://api.getengageai.app/admin/organizations \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Copper Kettle Cafe",
    "owner": { "email": "manager@copperkettle.example", "name": "Sam Patel" }
  }'

The response is the same as public signup: the organization, the owner's login block with a one-time password, and a first API key. Hand the whole login block to the customer; it includes the sign-in URL.

Compared with public signup, operators can also set plan (FREE, STARTER, GROWTH or ENTERPRISE), environment and settings. The slug is derived from the name, for example Café Números becomes cafe-numeros, unless you pass one. A slug you choose that is already taken returns 409.

The organization, its default agent profile, the owner and the first key are created together or not at all. New organizations start conservative: replies held for review, no stock claims and no commitments.

Looking up an organization

curl "https://api.getengageai.app/admin/organizations?limit=50" -H "Authorization: Bearer $ADMIN_TOKEN"
curl https://api.getengageai.app/admin/organizations/$ORG_ID -H "Authorization: Bearer $ADMIN_TOKEN"

The detail view shows members with their emails and lastLoginAt, and API keys with their prefixes and lastUsedAt. It never shows a password or a usable key.

Reissuing credentials

Credentials cannot be retrieved, only replaced.

# "We've lost the password": issues a new one and signs that person out everywhere.
curl -X POST https://api.getengageai.app/admin/organizations/$ORG_ID/password-reset \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" -d '{}'

# "We've lost every API key too": issues a new key.
curl -X POST https://api.getengageai.app/admin/organizations/$ORG_ID/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" -d '{ "name": "Replacement key" }'

A password reset applies to the owner unless you pass another member's email. It revokes every session that person had, which is what you want if a credential may have leaked.