Authentication API
The routes under /api/auth sign users in to the Data API and handle their accounts. Unlike the rest of the API, they take their own bodies, not { "data": … }; answers use the usual envelope, and a route with nothing to return (sign-out, the password and email routes, accepting an invitation) answers 204 No Content. See Authentication for how sessions and tokens are used.
| Route | Access | Body | Does |
|---|---|---|---|
POST /api/auth/login | public | { email, password } | { data: { token, user } }, a session token. Needs a role with API access |
POST /api/auth/logout | session | ends the session | |
GET /api/auth/me | session | the signed-in user | |
POST /api/auth/register | public | { email, password, name? } | creates an account, when self-registration is on |
POST /api/auth/password/forgot | public | { email } | emails a reset link; always answers 204 |
POST /api/auth/password/reset | public | { token, password } | sets a new password with a reset token |
POST /api/auth/password/change | session | { currentPassword, newPassword } | changes the signed-in user's password |
POST /api/auth/email/verify | public | { token } | marks the email verified |
POST /api/auth/email/resend | public or session | { email } without a session | sends a new verification link; without a session always answers 204 |
POST /api/auth/invitations/accept | public | { token, password } | accepts an invitation and sets the password |
GET /api/auth/oauth/{provider} | public | ?redirect_to= | starts sign-in with a provider |
GET /api/auth/oauth/{provider}/callback | the provider | ?code&state | finishes it, and redirects to redirect_to with the token |
"Session" routes take a session token, not an API token: Authorization: Bearer <token>.
Answers worth knowing
| Answer | When |
|---|---|
401 AUTHENTICATION_REQUIRED, Invalid email or password | a wrong password, a locked account, or an account without API access: the same answer, so nothing is revealed |
403 EMAIL_NOT_VERIFIED | a correct password on an unverified account, while verification is required |
400 INVALID_CURRENT_PASSWORD | a wrong current password on change |
403 PERMISSION_DENIED | registration while it's off; a password change on an account with no password yet |
401 SESSION_EXPIRED | an expired or revoked session |
forgot and resend always succeed, so they can't be used to find out which emails have accounts.
Your own pages
Invitation, reset and verification emails link to TotalBase's pages by default. To handle these steps in your own application, point the links at it in Settings › Access › Authentication (Email links); your page receives the token and calls the matching route above.