NUACOM API

Account & access

Auth

The Auth group holds the login endpoints and the password endpoints that go with them. Every token they issue is sent as Authorization: Bearer <token>, described in the Authentication guide.

Which token to use

Preferred: an API key. An account admin issues it on the portal's Settings → API Keys page. The key acts as the admin who created it, so it reaches everything an account admin can, never expires, and needs none of the endpoints below. Use it for integrations, scripts and servers.

When you need a token scoped to one specific user (with that user's narrower permissions and call-log visibility rather than an admin's), log in as that user with POST /v2/auth/login: it takes email, the plain-text password in pass (the API hashes it), remember and two_fa_code, and answers with a session token. A session token expires (30 days, or 90 with remember), so a long-running integration that does not need per-user restrictions should still prefer an API key.

Workflow

flowchart TD
    login["POST /v2/auth/login<br/>email, pass, remember"] --> answer{Answer}
    answer -- "200, two_fa_enabled: true" --> code["Ask the user for the emailed code"]
    code --> retry["POST /v2/auth/login<br/>+ two_fa_code"] --> answer
    answer -- "401, code: 4001" --> password["POST /v2/auth/update-password"] --> login
    answer -- "200, session_token" --> calls["Authorization: Bearer on every call<br/>for expire_in seconds"]
    calls --> logout["POST /v2/logout"]
    calls -- "401 from any endpoint" --> login
  1. POST /v2/auth/login with email, the password in pass and remember.
  2. If the answer is 200 with two_fa_enabled: true, a code has been emailed to the user: ask for it and repeat the same call with two_fa_code.
  3. If the answer is 401 with code: 4001, the password has expired: collect a new one, call POST /v2/auth/update-password with the plain-text password, new_password and new_password_confirmation, then log in again with the two_fa_code that call returns.
  4. Store session_token and send it as Authorization: Bearer <session_token>. Store expire_in too: the session is fixed-length (30 days, or 90 with remember) and is not extended by use.
  5. Call POST /v2/logout when you are done. A 401 from any endpoint means the session is gone: log in again.

Roles and access

  • No token is needed for the login and password endpoints; update-password identifies the user by email.
  • No account-admin requirement.
  • An account can enforce 2FA for every user, restrict logins to an IP allow-list (code: 4004) or disable password logins in favour of single sign-on (code: 4002).

Pitfalls

  • Send these calls to the central host https://api.api-nuacom.com. On an account subdomain they answer 404.
  • login and update-password take the password in plain text; send them over HTTPS only.
  • "2FA needed" is HTTP 200, not an error. Only a wrong or expired code is a 401.
  • Five failed logins from one IP address within five minutes lock that address for a few minutes.
  • update-password expires every existing session of the user, on every device.