Skip to content

Users

The following endpoints allow you to get, add, edit and delete users in your bucket.

✅

Quick Tip
Your authentication token will be required to perform the following requests.
You can get your authentication token in your user account settings located in Account Settings > Authentication. You can also get your token using the API with your email and password.

Get Users

Gets all users in your bucket.

⚠

Required
token must be passed as Authorization Bearer in the header of the request and you must have admin access to perform this operation.

Methods

GET $BASE_URL/buckets/${YOUR_BUCKET_SLUG}/users

Example Response

{
  "users": [
    {
      "id": "5e4d7eb92850c717ea93dba4",
      "first_name": "Starman",
      "last_name": "Jones",
      "email": "starman@milkyway.com",
      "username": "starman",
      "bio": "",
      "website": "",
      "twitter": "",
      "linkedin": "",
      "github": "",
      "company": "",
      "location": ""
    },
    {
      "id": "5f46a1c25711926847cd6b5c",
      "first_name": "Quasar",
      "last_name": "Jones",
      "email": "quasar@milkyway.com",
      "username": "quasar"
    }
  ],
  "total": 2
}

Get User

Gets user by id in your bucket.

⚠

Required
token must be passed as Authorization Bearer in the header of the request and you must have admin access to perform this operation.

Methods

GET $BASE_URL/buckets/${YOUR_BUCKET_SLUG}/users/${user_id}

Example Response

{
  "user": {
    "id": "5f46a1c25711926847cd6b5c",
    "first_name": "Quasar",
    "last_name": "Jones",
    "email": "quasar@milkyway.com",
    "username": "quasar"
  }
}

Add User

Add user to your bucket.

⚠

Required
token must be passed as Authorization Bearer in the header of the request and you must have admin access to perform this operation.

ParameterRequiredTypeDescription
first_namerequiredStringThe new user's first name
last_namerequiredStringThe new user's last name
emailrequiredStringThe new user's email
rolerequiredEnumadmin, developer, editor or contributor
publishing_restrictionsEnumdraft_only
additional_permissionsString / Array[String]users, settings, sort_metafields
object_typesrequired if role is contributorString / Array[String]Your Cosmic login password

Methods

POST $BASE_URL/buckets/${YOUR_BUCKET_SLUG}/users

Example Body (JSON)

{
  "first_name": "ABC",
  "last_name": "XYZ",
  "email": "abc@xyz.com",
  "role": "admin"
}

Example Response

{
  "message": "User added successfully."
}

Edit User

Edit user by id in your bucket.

⚠

Required
token must be passed as Authorization Bearer in the header of the request and you must have admin access to perform this operation.

ParameterRequiredTypeDescription
rolerequiredEnumadmin, developer, editor or contributor
publishing_restrictionsEnumdraft_only
additional_permissionsString / Array[String]users, settings, sort_metafields
object_typesrequired if role is contributorString / Array[String]Object Type slugs

Definition

PATCH $BASE_URL/buckets/${YOUR_BUCKET_SLUG}/users/${user_id}

Example Body (JSON)

{
  "role": "editor"
}

Example Response

{
  "message": "User role edited successfully from bucket."
}

Delete User

Delete user by id from your bucket.

⚠

Required
token must be passed as Authorization Bearer in the header of the request and you must have admin access to perform this operation.

Definition

DELETE $BASE_URL/buckets/${YOUR_BUCKET_SLUG}/users/${user_id}

Example Response

{
  "message": "User delete successfully from bucket."
}