REST API

Note

The REST API is enabled by default but can be disabled by setting OPENWISP_USERS_AUTH_API to False.

Live Documentation

General live API documentation, following the OpenAPI specification, is available at /api/v1/docs/.

Additionally, opening any of the endpoints listed below directly in the browser will show the browsable API interface of Django-REST-Framework, which makes it even easier to find out the details of each endpoint.

Obtain Authentication Token

/api/v1/users/token/

This endpoint only accepts the POST method and is used to retrieve the Bearer token that is required to make API requests to other endpoints.

Example usage:

curl -i -X POST http://localhost:8000/api/v1/users/token/ -d "username=openwisp" -d "password=1234"

HTTP/1.1 200 OK
Date: Wed, 05 Jun 2024 16:31:33 GMT
Server: WSGIServer/0.2 CPython/3.8.10
Content-Type: application/json
Vary: Accept
Allow: POST, OPTIONS
X-Frame-Options: DENY
Content-Length: 52
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"token": "7a2e1d3d008253c123c61d56741003db5a194256"}

Authenticating with the User Token

The authentication class openwisp_users.api.authentication.BearerAuthentication is used across the different OpenWISP modules for authentication.

To use it, first of all get the user token as described above in Obtain Authentication Token, then send the token in the Authorization header:

# Get the bearer token
TOKEN=$(curl -X POST http://localhost:8000/api/v1/users/token/ -d "username=openwisp" -d "password=1234" | jq -r .token)

# Get user list, send bearer token in authorization header
curl http://localhost:8000/api/v1/users/user/ -H "Authorization: Bearer $TOKEN"

List of Endpoints

For complete parameter details, see the Live Documentation and the Browsable Web Interface of each endpoint.

Request Password Reset

POST /api/v1/users/password/reset/

For an eligible user, this endpoint sends a password reset e-mail when the input parameter matches a username, e-mail address or phone number.

Unknown or ineligible identifiers receive the same response without an e-mail, so this endpoint cannot be used to find out whether an identifier is registered.

Example usage:

curl -i -X POST http://localhost:8000/api/v1/users/password/reset/ -d "input=openwisp"

Confirm Password Reset

POST /api/v1/users/password/reset/confirm/

Sets a new password given the uid and token received in the password reset e-mail, along with new_password1 and new_password2.

Example usage:

curl -i -X POST http://localhost:8000/api/v1/users/password/reset/confirm/ \
    -d "uid=<uid>" -d "token=<token>" \
    -d "new_password1=newpass123" -d "new_password2=newpass123"

Change Own Password

POST /api/v1/users/user/password/change/

Lets an authenticated user change their own password, given their old_password and a new one (new_password1, confirmed via new_password2). Unlike Change User Password below, this endpoint always operates on the requesting user.

Example usage:

curl -i -X POST http://localhost:8000/api/v1/users/user/password/change/ \
    -H "Authorization: Bearer $TOKEN" \
    -d "old_password=oldpass123" \
    -d "new_password1=newpass123" \
    -d "new_password2=newpass123"

Change User Password

PUT /api/v1/users/user/{id}/password/

Allows an authorized user to change another user's password. The id identifies the user whose password is changed.

List Groups

GET /api/v1/users/group/

Create New Group

POST /api/v1/users/group/

Get Group Detail

GET /api/v1/users/group/{id}/

Change Group Detail

PUT /api/v1/users/group/{id}/

Patch Group Detail

PATCH /api/v1/users/group/{id}/

Delete Group

DELETE /api/v1/users/group/{id}/

List Email Addresses

GET /api/v1/users/user/{id}/email/

Add Email Address

POST/api/v1/users/user/{id}/email/

Get Email Address

GET /api/v1/users/user/{id}/email/{id}/

Change Email Address

PUT /api/v1/users/user/{id}/email/{id}/

Patch Email Address

PATCH /api/v1/users/user/{id}/email/{id}/

Make/Unmake Email Address Primary

PATCH /api/v1/users/user/{id}/email/{id}/

Mark/Unmark Email Address as Verified

PATCH /api/v1/users/user/{id}/email/{id}/

Remove Email Address

DELETE /api/v1/users/user/{id}/email/{id}/

List Organizations

GET /api/v1/users/organization/

Create new Organization

POST /api/v1/users/organization/

Get Organization Detail

GET /api/v1/users/organization/{id}/

Change Organization Detail

PUT /api/v1/users/organization/{id}/

Patch Organization Detail

PATCH /api/v1/users/organization/{id}/

Delete Organization

DELETE /api/v1/users/organization/{id}/

List Users

GET /api/v1/users/user/

Create User

POST /api/v1/users/user/

Note

Passing true to the optional is_verified field allows creating users with their email address flagged as verified. This will also skip sending the verification link to their email address.

When creating organization memberships, the organization manager flag is represented internally by the is_admin field in the organization_users payload.

Get User Detail

GET /api/v1/users/user/{id}/

Change User Detail

PUT /api/v1/users/user/{id}/

Note

When editing organization memberships, the organization manager flag is represented internally by the is_admin field in the organization_users payload.

Patch User Detail

PATCH /api/v1/users/user/{id}/

Note

When patching organization memberships, the organization manager flag is represented internally by the is_admin field in the organization_users payload.

Delete User

DELETE /api/v1/users/user/{id}/

Settings

Developer Docs