Users

A User represents a single account that can authenticate with a Bucket. Each User can have its own authentication settings, directory permissions, and more.

The User Model

The User model contains all the information about the users you have created.

Properties

Name
id
Type
string
Description
Unique identifier for the user.
Name
bucket_id
Type
string
Description
The id of the Bucket this user is attached to.
Name
username
Type
string
Description
The username for this User.
Name
password
Type
string
Description
The password for this User.
Name
active
Type
boolean
Description
Whether or not the User is currently active. If set to false, all connection attempts will be rejected.
Name
permissions
Type
object
Description
An object of directory paths and their permissions for this User. An empty dictionary means that the user can navigate/access any directories in this Bucket. You can use wildcard paths as well, like /dir1/*/dir2.
Name
created_at
Type
timestamp
Description
Unix Timestamp of when the user was created.

POST/v1/users

Create a User

Use this route to create a new User for a specific Bucket. Note that the password for the user will never be returned with a saved/updated User object.

Request

{
    "username": "johndoe",
    "password": "password123",
    "bucket_id": "bio_test_buc_1amaj5125as"
}

Response

{
    "id": "bio_test_usr_1amaj5125as",
    "username": "johndoe",
    "active": true,
    "permissions": {},
    "created_at": 692233200
}

GET/v1/buckets/{bucket_id}/users

Fetch All Users

Use this route to fetch the Users attached to a specific Bucket.

Request

GET

/v1/buckets/{bucket_id}/users

curl -X GET https://api.usebuckets.io/v1/buckets/{bucket_id}/users \
  -H "Authorization: Bearer {token}"

Response

{
    "has_more": true,
    "next_uri": "/api/v1/users?after=bio_test_usr_8gkde9034zx",
    "data": [
        {
            "id": "bio_test_usr_1amaj5125as",
            "username": "johndoe",
            "active": true,
            "permissions": {},
            "created_at": 692233200
        },
        {
            "id": "bio_test_usr_8gkde9034zx",
            "username": "janedoe",
            "active": false,
            "permissions": {
                "/": "read",
                "/uploads": "write"
            },
            "created_at": 692233200
        }
    ]
}

PATCH/v1/users/{user_id}

Update a User

Use this route to update the username, password, permissions, or active status of a User. You must include at least one of those properties for the call to be successful.

Request

{
  "password": "newpassword123"
}

Response

{
    "id": "bio_test_usr_1amaj5125as",
    "username": "johndoe",
    "active": true,
    "permissions": {},
    "created_at": 692233200
}

DELETE/v1/users/{bucket_id}

Delete a User

Use this route when you want to fully delete a User. This action is not reversible. This will not affect any files that this user has uploaded.

Response

HTTP 200