Skip to content
engage-ai

API reference

Authentication

Organization sign-in, sessions and password changes

For concepts and a walkthrough, read Authentication.

Sign in and receive an access token

POST/auth/login

Exchange the credentials issued at provisioning for a token, then send it as Authorization: Bearer <token> on every other endpoint.

Every failure returns the same 401 with the same message. Distinguishing "no such account" from "wrong password" would turn this into an account-enumeration oracle, so the specific reason is logged rather than returned.

mustChangePassword is true while the password is the one an administrator issued.

Auth
None
Body
application/json

Request body

  • emailstring (email)required

    Max 320 characters

  • passwordstringrequired

    Max 512 characters

  • organizationIdstring (uuid)

    Required only when the account belongs to more than one organization.

Response fields 200
  • accessTokenstringrequired

    Send as Authorization: Bearer <token> on every other endpoint. Revocable, unlike a self-contained token.

  • expiresAtstring (date-time)required
  • mustChangePasswordbooleanrequired

    True while the password is the one an administrator issued.

  • userobjectrequired
  • user.idstring (uuid)required
  • user.emailstring (email)required
  • user.namestring | nullrequired
  • organizationobjectrequired
  • organization.idstring (uuid)required
  • organization.namestringrequired
  • organization.slugstringrequired
  • organization.rolestringrequired

LoginResult

  • accessTokenstringrequired

    Send as Authorization: Bearer <token> on every other endpoint. Revocable, unlike a self-contained token.

  • expiresAtstring (date-time)required
  • mustChangePasswordbooleanrequired

    True while the password is the one an administrator issued.

  • userobjectrequired
  • user.idstring (uuid)required
  • user.emailstring (email)required
  • user.namestring | nullrequired
  • organizationobjectrequired
  • organization.idstring (uuid)required
  • organization.namestringrequired
  • organization.slugstringrequired
  • organization.rolestringrequired

Responses

  • 200Signed in.
  • 401Invalid email or password.
Request
curl -X POST "https://api.getengageai.app/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "manager@copperkettle.example",
    "password": "mFGVaAer-jKcyPp34-qxmLNojm"
  }'
Response · 200
{
  "accessToken": "eng_sess_76bc0bae.2DrK9vYw…",
  "expiresAt": "2026-10-16T09:30:00.000Z",
  "mustChangePassword": true,
  "user": {
    "id": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
    "email": "owner@acme.example",
    "name": "Trailhead Mid GTX Boot"
  },
  "organization": {
    "id": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
    "name": "Trailhead Mid GTX Boot",
    "slug": "copper-kettle-cafe",
    "role": "string"
  }
}

End the current session

POST/auth/logout

Idempotent. Takes effect on the next request; there is no grace period.

Auth
Session token or API key
Response fields 200
  • loggedOuttruerequired

Responses

  • 200Signed out.
  • 401Missing, expired or already-revoked credential.
  • 409The credential is an API key, which has no session.
Request
curl -X POST "https://api.getengageai.app/auth/logout" \
  -H "Authorization: Bearer $ENGAGE_API_KEY"
Response · 200
{
  "loggedOut": true
}

Describe the current credential

GET/auth/me

Useful for a client that holds a token and needs to know what it is — which tenant, whether it is a session or an API key, and whether a password change is outstanding.

Auth
Session token or API key
Response fields 200
  • organizationIdstring (uuid)required
  • kindenumrequired

    Which credential authenticated this request.

    One of session, api_key

  • scopesstring[]required
  • userIdstring (uuid) | nullrequired
  • mustChangePasswordboolean | nullrequired

CurrentPrincipal

  • organizationIdstring (uuid)required
  • kindenumrequired

    Which credential authenticated this request.

    One of session, api_key

  • scopesstring[]required
  • userIdstring (uuid) | nullrequired
  • mustChangePasswordboolean | nullrequired

Responses

  • 200The authenticated principal.
  • 401Missing, expired or revoked credential.
Request
curl "https://api.getengageai.app/auth/me" \
  -H "Authorization: Bearer $ENGAGE_API_KEY"
Response · 200
{
  "organizationId": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
  "kind": "session",
  "scopes": [
    "string"
  ],
  "userId": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
  "mustChangePassword": true
}

Change your password

POST/auth/password

Clears mustChangePassword and revokes every session, including the one making this call — sign in again afterwards. Revoking the rest is the point as much as the new password is: a change that leaves other tokens live does not lock anyone out.

Auth
Session token or API key
Body
application/json

Request body

  • currentPasswordstringrequired

    Max 512 characters

  • newPasswordstringrequired

    At least 12 characters. Length is the requirement; composition rules are not.

    Min 12 characters · Max 512 characters

Response fields 200
  • changedtruerequired
  • sessionsRevokedintegerrequired

    Every session, including the one that made this call. Sign in again.

    Min -9007199254740991

Responses

  • 200Changed. All sessions ended.
  • 401The current password did not match.
  • 409The credential is an API key, not a signed-in user.
  • 422The new password is too short, or contains the email.
Request
curl -X POST "https://api.getengageai.app/auth/password" \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "mFGVaAer-jKcyPp34-qxmLNojm",
    "newPassword": "a-long-passphrase-you-chose"
  }'
Response · 200
{
  "changed": true,
  "sessionsRevoked": 0
}