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

Since the detailed explanation is contained in the Live Documentation and in the Browsable Web Interface of each endpoint, here we'll provide just a list of the available endpoints, for further information please open the URL of the endpoint in your browser.

Change User password

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

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.

Get User Detail

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

Change User Detail

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

Patch User Detail

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

Delete User

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

Settings

Developer Docs