Users and Groups API in Wasabi AiR

  • Updated on May 20, 2024
  • Published on May 17, 2024
  • 2 minute(s) read

You can create and manage users with a RESTful interface in Wasabi AiR with the following object and endpoints.

Users API

User Object

{
    "id": "5833031d7d551417c16891d475429de3",
    "email": "testuser@wasabi.com",
    "first_name": "Morgan",
    "last_name": "Freeman",
    "enabled": true,
    "role_id": "59de4bb09221034b071d83db64950d34",
    "created_at": "2016-11-22T00:00:00Z",
    "updated_at": "2016-11-22T01:22:21.421327Z"
}
  • id - (string) The ID of the user (auto-generated).
  • email - (string) The email (must be unique).
  • first_name - (string) The user's first name.
  • last_name - (string) The user's last name.
  • enabled - (bool) If true, the account for the user is enabled (default: true).
  • role_id - (string) The ID of the role assigned to this user.
  • password - (string) The user password, which is only for password creation or change. The password is not stored.
  • created_at - (datetime) The date and time of the creation (auto-calculated).
  • updated_at - (datetime) The date and time of the last update (auto-calculated).

Creating a User

POST /api/data/users
{
    "email": "ada@wasabi.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "password": "secret1234",
    "role_id": "59de4bb09221034b071d83db64950d34"
}

Response

The response is 201 with the User object.

{
    "id": "583ba3125b9f5421e1cb5702deb8d45e",
    "email": "ada@wasabi.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "enabled": true,
    "role_id": "59de4bb09221034b071d83db64950d34",
    "created_at": "2016-11-28T00:00:00Z",
    "updated_at": "2016-11-28T14:22:58.44874Z"
}

Retrieving the User

GET /api/data/users/{id}
  • {id} - (string) The user ID.

For example: GET /api/data/users/583ba3125b9f5421e1cb5702deb8d45e

Response

{
    "id": "583ba3125b9f5421e1cb5702deb8d45e",
    "email": "ada@wasabi.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "enabled": true,
    "role_id": "59de4bb09221034b071d83db64950d34",
    "created_at": "2016-11-28T00:00:00Z",
    "updated_at": "2016-11-28T14:22:58.44874Z"
}

Updating a User

PUT /api/data/users/{id}
  • {id} - (string) The user ID.
{
    "email": "ada.lovelace@wasabi.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "enabled": false,
    "role_id": "59de4bb09221034b071d83db64950d34"
}

Partially Updating a User

PATCH /api/data/users/{id}
  • {id} - (string) The user ID.
{
    "admin": false,
    "last_name": "Potter"
}

Updating a User Password

This API can be used only to change the password for the user who is currently logged in. Administrators cannot use this API to change other users’ passwords.

PUT /api/data/users/{id}/password
  • {id} - (string) The user ID.
{
    "password": "newsecret12345"
}

Retrieving All Users

GET /api/data/users

Response

{
    "users": [
        {
            "id": "583ba3125b9f5421e1cb5702deb8d45e",
            "email": "ada@wasabi.com",
            "first_name": "Ada",
            "last_name": "Lovelace",
            "enabled": true,
            "role_id": "59de4bb09221034b071d83db64950d34",
            "created_at": "2016-11-28T00:00:00Z",
            "updated_at": "2016-11-28T14:22:58.44874Z"
        },
        {...},
        {...}
    ]
}

Retrieving Users by Email

GET /api/data/users?email=ada@wasabi.com

Response

[
    {
        "id": "583ba3125b9f5421e1cb5702deb8d45e",
        "email": "ada@wasabi.com",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "enabled": true,
        "role_id": "59de4bb09221034b071d83db64950d34",
        "created_at": "2016-11-28T00:00:00Z",
        "updated_at": "2016-11-28T14:22:58.44874Z"
    }
]

Users in Groups API

You can add or remove users from groups with the following APIs.

Adding a User to a Group

PUT /api/data/v3/users/{id}/groups/{group_id}
  • {id} - (string) The user ID.
  • {group_id} - (string) The group ID.

Response

Response if the group is added:

{
    "ok": true
}

Removing a User From a Group

DELETE /api/data/v3/users/{id}/groups/{group_id}
  • {id} - (string) The user ID.
  • {group_id} - (string) The group ID.

Listing the Groups for a User

GET /api/data/v3/users/{id}/groups
  • {id} - (string) The user ID.
{
    "groups": [
        {
            "id": "ADMIN",
            "name": "Admin"
        },
        {
            "id": "EDITORS",
            "name": "Editors"
        }
    ]
}

 Groups API

You can create and manage groups with a RESTful interface in Wasabi AiR with the following object and endpoints.

Group Object

{
    "id": "EDITORS",
    "name": "Editors",
    "description": "Description of what editors have access to"
}
  • id - (string) The ID of the group (auto-calculated based on the name of the group).
  • name - (string) The name of the group.
  • description - (string) A description of what the group is about.

Creating a Group

POST /api/data/v3/groups
{
    "name": "Editors",
    "description": "Editors can access daily clips"
}

Response

The response is 201 with the Group object.

{
    "id": "EDITORS",
    "name": "Editors",
    "description": "Editors can access daily clips"
}

Updating a Group

PUT /api/data/v3/groups/{id}
  • id - (string) The ID of the group.

For example:

PUT /api/data/v3/groups/EDITORS
{
    "name": "Video Editors",
    "description": "My new description"
}

Retrieving a Group

GET /api/data/v3/groups/{id}
  • id - (string) The ID of the group.

Response

{
    "id": "EDITORS",
    "name": "Editors",
    "description": "Explanation of this group"
}

Retrieving All Groups

GET /api/data/v3/groups

Response

{
    "groups": [
      {
        "id": "ADMIN",
        "name": "Admin",
            "description": "Admins have full access"
      },
      {
        "id": "EDITORS",
        "name": "Editors",
            "description": "Editor can access only daily clips"
      },
        {...}
    ]
}

Deleting a Group

DELETE /api/data/v3/groups/{id}
  • id - (string) The ID of the group.

For example:

DELETE /api/data/v3/groups/EDITORS