Skip to main content
The Auth service handles user registration, login, session management, and credential operations. Its base URL is configured via REACT_APP_AUTH_API_BASE_URL (default: https://api.makakoo.com/ma-authentication-ms/v1/api). All requests require the Api-Key header. Endpoints that operate on an authenticated session also require Authorization: Bearer <token>.

​
Login

POST /oauth/token
Authenticate a user with username and password. Returns access and refresh tokens. Request headers: Api-Key
​
username
string
required
The user’s email address or phone number.
​
password
string
required
The user’s password.
curl -X POST https://api.makakoo.com/ma-authentication-ms/v1/api/oauth/token \
  -H "Content-Type: application/json" \
  -H "Api-Key: <your_api_key>" \
  -d '{"username": "[email protected]", "password": "secret"}'
​
data.id
string
The user’s unique ID.
​
data.type
string
Always "session".
​
data.attributes.accessToken
string
Short-lived JWT used to authenticate subsequent requests.
​
data.attributes.refreshToken
string
Long-lived token used to obtain a new access token when the current one expires.
​
data.attributes.email
string
The authenticated user’s email address.
​
data.attributes.firstName
string
The user’s first name.
​
data.attributes.lastName
string
The user’s last name.
Rate limiting: Login attempts are rate-limited per username. Exceeding the limit returns 429 Too Many Requests.

​
Register

POST /users
Create a new user account. Depending on the registration method, the response may indicate that account activation is required before the user can log in. Request headers: Api-Key
​
username
string
required
Email address or phone number for the new account.
​
password
string
required
Password for the new account.
​
method
string
Registration method. Use "phone" for phone-based registration; omit or use "email" for email-based registration.
curl -X POST https://api.makakoo.com/ma-authentication-ms/v1/api/users \
  -H "Content-Type: application/json" \
  -H "Api-Key: <your_api_key>" \
  -d '{"username": "[email protected]", "password": "secret"}'
On success without activation required — returns 200 with tokens (same shape as Login). On success with activation required — returns 201:
​
user_id
string
The new user’s ID. Pass this to the account activation endpoints.
​
status
number
201 when activation is required.
​
message
string
Human-readable message describing the next step.
​
activationRequired
boolean
true when the account must be activated before logging in.
Rate limiting: Registration attempts are rate-limited per username.

​
Activate Account (Email)

POST /users/{userId}/activate/email
Activate a newly registered account using the 6-digit verification code sent by email. Request headers: Api-Key
​
userId
string
required
The user ID returned from the registration response.
​
code
string
required
The 6-digit verification code from the activation email.
Response: Returns tokens and user data in the same shape as the Login response.

​
Activate Account (Phone)

POST /users/{userId}/activate/phone
Activate a newly registered account using the 6-digit verification code sent by SMS. Request headers: Api-Key
​
userId
string
required
The user ID returned from the registration response.
​
code
string
required
The 6-digit verification code from the SMS.
Response: Returns tokens and user data in the same shape as the Login response.

​
Resend Activation Code

POST /users/{userId}/resend_activation
Resend the activation code to the user’s email or phone. Request headers: Api-Key
​
userId
string
required
The user ID returned from the registration response.

​
Logout

GET /oauth/token/revoke
Revoke the current access token, effectively ending the session. Request headers: Api-Key, Authorization: Bearer <token> 
curl https://api.makakoo.com/ma-authentication-ms/v1/api/oauth/token/revoke \
  -H "Api-Key: <your_api_key>" \
  -H "Authorization: Bearer <access_token>"
Response: 200 OK. If the token was already expired, returns 401 — in both cases, clear locally stored tokens.

​
Refresh Token

POST /oauth/token/refresh
Exchange a refresh token for a new access token and refresh token pair. Request headers: Api-Key
​
refresh_token
string
required
The refresh token from a previous login or refresh response.
curl -X POST https://api.makakoo.com/ma-authentication-ms/v1/api/oauth/token/refresh \
  -H "Content-Type: application/json" \
  -H "Api-Key: <your_api_key>" \
  -d '{"refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."}'
Response: Returns the same shape as Login with new accessToken and refreshToken values.

​
Check Token Info

GET /oauth/token/info
Verify that an access token is valid and retrieve its associated claims. Request headers: Api-Key, Authorization: Bearer <token> 
curl https://api.makakoo.com/ma-authentication-ms/v1/api/oauth/token/info \
  -H "Api-Key: <your_api_key>" \
  -H "Authorization: Bearer <access_token>"
Response: 200 OK with token claims on success, 401 Unauthorized if expired or invalid.

​
Validate Email

GET /users/validate/email
Check whether an email address is valid and available for registration. Request headers: Api-Key
​
email
string
required
The email address to validate.
​
valid
boolean
true if the email address is syntactically valid.
​
exists
boolean
true if an account with this email address already exists.
Rate limiting: Validation requests are rate-limited per address.

​
Validate Phone

GET /users/validate/phone
Check whether a phone number is valid and available for registration. Request headers: Api-Key
​
phoneNumber
string
required
The phone number without country code.
​
countryCode
string
required
The country calling code (e.g., "1" for US/Canada, "44" for UK).
​
valid
boolean
true if the phone number is valid.
​
exists
boolean
true if an account with this phone number already exists.

​
Request Password Reset

POST /users/password/reset_request
Send a password reset email to the specified address. Request headers: Api-Key
​
email
string
required
The email address associated with the account.
curl -X POST https://api.makakoo.com/ma-authentication-ms/v1/api/users/password/reset_request \
  -H "Content-Type: application/json" \
  -H "Api-Key: <your_api_key>" \
  -d '{"email": "[email protected]"}'
Response: 200 OK. The response does not confirm whether the email exists to prevent enumeration. Rate limiting: Password reset requests are rate-limited per email address.

​
Reset Password with Token

POST /users/password/reset
Set a new password using the reset token from the password reset email. Does not require an existing session. Request headers: Api-Key
​
email
string
required
The user’s email address.
​
new_password
string
required
The new password to set.
​
reset_token
string
required
The reset token from the password reset email.

​
Change Password (Authenticated)

POST /users/password/change
Change the password for the currently authenticated user. Request headers: Api-Key, Authorization: Bearer <token>
​
new_password
string
required
The new password to set.

Build docs developers (and LLMs) love

Get started for freeTalk to us