From 715cf8d39e1ba5a5222eb683f3c5270d73cf541d Mon Sep 17 00:00:00 2001 From: Ana Domonji Date: Fri, 27 Mar 2026 11:22:44 +0100 Subject: [PATCH 1/2] Add users docs Signed-off-by: Ana Domonji --- docs/api.md | 222 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 217 insertions(+), 5 deletions(-) diff --git a/docs/api.md b/docs/api.md index a742ece..32a5521 100644 --- a/docs/api.md +++ b/docs/api.md @@ -62,6 +62,45 @@ Access-Control-Allow-Methods: * Access-Control-Allow-Headers: * ``` +### Self-Register User +Allows a new user to register themselves. The system sends an email verification link to complete registration. + +> Must-have: `user` object (with `email` and `password`) and `redirect_path` (URL for verification) + +```bash +curl -s -S -i -X POST -H "Content-Type: application/json" http://localhost/register \ +-d '{"user": { "email": "", "password": ""}, "redirect_path": "https://example.com/verify"}' +``` + +Response (on success, returns empty JSON `{}` but sends email verification link): +```bash +HTTP/1.1 201 Created +Content-Type: application/json +Date: Thu, 11 Apr 2024 12:00:00 GMT +Content-Length: 2 + +{} +``` + +### Verify Email +Completes user registration by verifying the e-mail using the token sent during self-registration. + +> Must-have: `email_token` (from the verification email) + +```bash +curl -s -S -i -X POST "http://localhost/register/verify?email_token=" +``` + +Response: +```bash +HTTP/1.1 200 OK +Content-Type: application/json +Date: Thu, 11 Apr 2024 12:05:00 GMT +Content-Length: 45 + +{"created":true,"id":"d782b42b-e317-4cd7-9dd0-4e2ea0f349c8"} +``` + ### View User You can always check the user entity that is logged in by entering the user ID and `user_token`. @@ -89,6 +128,32 @@ Access-Control-Allow-Headers: * {"id":"d782b42b-e317-4cd7-9dd0-4e2ea0f349c8","email":"test@email.com"} ``` +### View Profile +Retrieve the profile of the currently logged-in user. + +> Must-have: `user_token` (Bearer token) + +```bash +curl -s -S -i -X GET -H "Authorization: Bearer " http://localhost/users/profile +``` + +Response: +```bash +HTTP/1.1 200 OK +Content-Type: application/json +Date: Thu, 11 Apr 2024 12:10:00 GMT +Content-Length: 120 + +{ + "id": "d782b42b-e317-4cd7-9dd0-4e2ea0f349c8", + "email": "test@email.com", + "metadata": { + "foo": "bar" + }, + "role": "user" +} +``` + ### List Users You can get all users in the database by calling this function @@ -116,6 +181,40 @@ Access-Control-Allow-Headers: * {"total":2,"offset":0,"limit":10,"Users":[{"id":"4bf4a13a-e9c3-4207-aa11-fe569986c301","email":"admin@example.com"},{"id":"d782b42b-e317-4cd7-9dd0-4e2ea0f349c8","email":"test@email.com"}]} ``` +### Search Users +Search users with optional filters such as status, email, and metadata. Supports pagination and ordering. + +> Must-have: `user_token` (Bearer token) +> Optional JSON body fields: `offset`, `limit`, `order`, `dir`, `status`, `email`, `metadata` + +```bash +curl -s -S -i -X POST -H "Authorization: Bearer " -H "Content-Type: application/json" \ http://localhost/users/search -d '{"offset": 0, +"limit": 10, "order": "id", "dir": "desc", "status": "enabled", "email": "example@email.com", "metadata": {"foo":"bar"}}' +``` + +Response: +```bash +HTTP/1.1 200 OK +Server: nginx/1.16.0 +Date: Thu, 11 Apr 2024 12:10:00 GMT +Content-Type: application/json +Content-Length: 120 + +{ + "total": 1, + "offset": 0, + "limit": 10, + "Users": [ + { + "id": "d782b42b-e317-4cd7-9dd0-4e2ea0f349c8", + "email": "example@email.com", + "metadata": {"foo":"bar"}, + "status": "enabled" + } + ] +} +``` + ### Update User Updating user's metadata @@ -142,6 +241,48 @@ Access-Control-Allow-Methods: * Access-Control-Allow-Headers: * ``` +#### Request Password Reset +Request a password reset link to be sent to the user's email. The link will contain a token used for resetting the password. + +> Must-have: `email` and `redirect_path` + +```bash +curl -s -S -i -X POST -H "Content-Type: application/json" \ http://localhost/password/reset-request -d '{"email": "user@example.com", +"redirect_path": "/reset-password"}' +``` + +Response: +```bash +HTTP/1.1 200 OK +Server: nginx/1.16.0 +Date: Thu, 11 Apr 2024 12:30:00 GMT +Content-Type: application/json +Content-Length: 32 + +{ + "msg": "Password reset email sent" +} +``` + +#### Reset Password +Use the token received by email to set a new password. Both `password` and `confirm_password` must match. + +> Must-have: `token`, `password`, `confirm_password` + +```bash +curl -s -S -i -X PUT -H "Content-Type: application/json" \ http://localhost/password/reset -d '{"token": "", +"password": "", "confirm_password": ""}' +``` + +Response: +```bash +HTTP/1.1 200 OK +Server: nginx/1.16.0 +Date: Thu, 11 Apr 2024 12:31:00 GMT +Content-Type: application/json +Content-Length: 0 +``` + ### Change Password Changing the user password can be done by calling the update password function @@ -167,6 +308,77 @@ Access-Control-Allow-Methods: * Access-Control-Allow-Headers: * ``` +### OAuth Login +The Mainflux system supports login via OAuth providers such as Google and GitHub. This flow involves two endpoints: initiating the OAuth login and handling the provider callback. + +#### Initiate OAuth Login +Redirect the user to the OAuth provider's login page. You can optionally provide an `inviteID` and a `redirect_path` where the user should be redirected after login. + +> Must-have: `provider` (Google or GitHub) +> Optional query params: `invite_id`, `redirect_path` + +```bash +curl -s -S -i -X GET "http://localhost/users/oauth/google?invite_id=&redirect_path=/dashboard" +``` + +Response: +```bash +{ + "state": "", + "verifier": "", + "invite_id": "", + "redirect_path": "/dashboard", + "redirect_url": "https://accounts.google.com/o/oauth2/auth?client_id=...&state=&code_challenge=" +} +``` + +#### OAuth Callback +After the user authenticates with the OAuth provider, the provider redirects to this endpoint with a code and state. This endpoint completes the login process and returns the final redirect URL. + +> Must-have: `provider` (Google or GitHub), `code`, `state` (from OAuth provider) +> Cookies: `state` and `verifier` must be set + +```bash +curl -s -S -i -X GET "http://localhost/users/oauth/google/callback?code=&state=" +``` + +Response: +```bash +{ + "redirect_url": "https://localhost/home?token=" +} +``` + +#### Enable User +Activate a user account. Requires admin privileges. + +> Must-have: `user_token` (Bearer token), `id` (user ID) + +```bash +curl -s -S -i -X POST -H "Authorization: Bearer " \ http://localhost/users//enable +``` + +Response: +```bash +HTTP/1.1 200 OK +Content-Type: application/json +``` + +#### Disable User +Deactivate a user account. Requires admin privileges. + +> Must-have: `user_token` (Bearer token), `id` (user ID) + +```bash +curl -s -S -i -X POST -H "Authorization: Bearer " \ http://localhost/users//disable +``` + +Response: +```bash +HTTP/1.1 200 OK +Content-Type: application/json +``` + ## Orgs ### Create Org @@ -273,10 +485,10 @@ each representing a user you want to add to the organization. Each object must include: -- **email**: The email address of the user to be added to the organization. +- **email**: The email address of the user to be added to the organization. Must refer to an existing registered user. -- **role**: The role you want to assign to the user within the organization. +- **role**: The role you want to assign to the user within the organization. Only roles listed in the [Roles Section](authorization.md#roles) are allowed. ```bash @@ -550,10 +762,10 @@ each representing a user you want to **add** to the group. Each object must include: -- **member_id**: The UUID of the user to be added to the group. +- **member_id**: The UUID of the user to be added to the group. Must refer to an existing registered user. -- **role**: The role to assign to the user within the group. +- **role**: The role to assign to the user within the group. Only roles listed in the [Roles Section](authorization.md#roles) are allowed. ```bash @@ -773,7 +985,7 @@ Access-Control-Expose-Headers: Location ``` ### List Profiles by Group -Get all profiles by a certain group where the user has access +Get all profiles by a certain group where the user has access > Must-have: `user_token`, `` From 645e6e7f2272614719246dd7dc000d11d14f25c6 Mon Sep 17 00:00:00 2001 From: Ana Domonji Date: Tue, 14 Apr 2026 08:43:32 +0200 Subject: [PATCH 2/2] Fix response for ouath login Signed-off-by: Ana Domonji --- docs/api.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/api.md b/docs/api.md index 32a5521..dac7c8e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -324,11 +324,7 @@ curl -s -S -i -X GET "http://localhost/users/oauth/google?invite_id=& Response: ```bash { - "state": "", - "verifier": "", - "invite_id": "", - "redirect_path": "/dashboard", - "redirect_url": "https://accounts.google.com/o/oauth2/auth?client_id=...&state=&code_challenge=" + "url": "https://accounts.google.com/o/oauth2/auth?client_id=...&state=...&code_challenge=..." } ```