Users

The following endpoints enable you to get Cosmic user info as well as create, read, update, and delete users in your Bucket.

🔑

Get your token
Your authentication token will be required to perform the following requests.
You can get your token using the authentication method with your email and password.

Endpoints

Get Cosmic user information.


GET /v2/user

Perform actions on users in a Bucket.


GET /v2/buckets/${YOUR_BUCKET_SLUG}/users
POST /v2/buckets/${YOUR_BUCKET_SLUG}/users
GET /v2/buckets/${YOUR_BUCKET_SLUG}/users/:id
PATCH /v2/buckets/${YOUR_BUCKET_SLUG}/users/:id
DELETE /v2/buckets/${YOUR_BUCKET_SLUG}/users/:id

Data Model

Attribute	Type	Notes
id	String	Unique identifier for User
first_name	String	User first name
last_name	String	User last name
email	String	User email
avatar_url	String	User avatar URL
username	String	URL-friendly username
bio	String	User bio
website	String	User website
twitter	String	User Twitter profile URL
linkedin	String	User LinkedIn profile URL
github	String	User GitHub profile URL
company	String	User company name
location	String	User location

Get Cosmic User

Gets user info from access token. See authentication section to get access token using email and password.

⚠

Required
token must be passed as Authorization Bearer in the header of the request.

Definition


GET /v2/user

Methods

cURL
Node.js
GraphQL


curl https://api.cosmicjs.com/v2/user \
    -H "Authorization: Bearer <TOKEN>"

Example Response


{
  "user": {
    "id": "5f46a1c25711926847cd6b5c",
    "first_name": "Quasar",
    "last_name": "Jones",
    "email": "quasar@milkyway.com",
    "username": "quasar",
    "avatar_url": "https://imgix.cosmicjs.com/e07818a0-51f0-11eb-9dee-df51ce912356-starry.jpg"
  }
}

Get Bucket Users

Gets all users in a 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


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

Methods

Node.js
cURL
GraphQL


bucket.getUsers()

Example Request


const Cosmic = require("cosmicjs")({
  token: "your-token-from-auth-request", // required
});
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
});
const data = await bucket.getUsers();

Example Response


{
  "users": [
    {
      "id": "5e4d7eb92850c717ea93dba4",
      "first_name": "Starman",
      "last_name": "Jones",
      "email": "starman@milkyway.com",
      "username": "starman",
      "bio": "",
      "website": "",
      "twitter": "",
      "linkedin": "",
      "github": "",
      "company": "",
      "location": "",
      "avatar_url": "https://imgix.cosmicjs.com/e07818a0-51f0-11eb-9dee-df51ce912356-starry.jpg"
    },
    {
      "id": "5f46a1c25711926847cd6b5c",
      "first_name": "Quasar",
      "last_name": "Jones",
      "email": "quasar@milkyway.com",
      "username": "quasar",
      "avatar_url": "https://imgix.cosmicjs.com/e07818a0-51f0-11eb-9dee-df51ce912356-quasar.jpg"
    }
  ],
  "total": 2
}

Get Bucket 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.

Definition


GET /v2/buckets/${YOUR_BUCKET_SLUG}/users/:id

Methods

Node.js
cURL
GraphQL


bucket.getUser()

Example Request


const Cosmic = require("cosmicjs")({
  token: "your-token-from-auth-request", // required
});
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
});
const params = {
  id: "5357ef811693be2118000001",
};
const data = await bucket.getUser(params);

Example Response


{
  "user": {
    "id": "5f46a1c25711926847cd6b5c",
    "first_name": "Quasar",
    "last_name": "Jones",
    "email": "quasar@milkyway.com",
    "username": "quasar",
    "avatar_url": "https://imgix.cosmicjs.com/e07818a0-51f0-11eb-9dee-df51ce912356-starry.jpg"
  }
}

Add User to Bucket

Add a 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.

Definition


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

Parameter	Required	Type	Description
first_name	required	String	The new user's first name
last_name	required	String	The new user's last name
email	required	String	The new user's email
role	required	Enum	`admin`, `developer`, `editor` or `contributor`
publishing_restrictions		Enum	`draft_only`
additional_permissions		String / Array[String]	`users`, `settings`, `sort_metafields`
object_types	required if role is `contributor`	String / Array[String]	Your Cosmic login password

Methods

Node.js
cURL
GraphQL
CLI


bucket.addUser()

Example Request


const Cosmic = require("cosmicjs")({
  token: "your-token-from-auth-request", // required
});
const bucket = Cosmic.bucket({
  slug: "YOUR_BUCKET_SLUG",
});
const params = {
  email: "newuser@example.com",
  role: "editor",
  first_name: "Quasar",
  last_name: "Jones",
};
const data = await bucket.addUser(params);

Example Response


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

Edit User in Bucket

Edit user 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.

Definition


PATCH /v2/buckets/${YOUR_BUCKET_SLUG}/users/:id

Parameter	Required	Type	Description
role	required	Enum	`admin`, `developer`, `editor` or `contributor`
publishing_restrictions		Enum	`draft_only`
additional_permissions		String / Array[String]	`users`, `settings`, `sort_metafields`
object_types	required if role is `contributor`	String / Array[String]	Object Type slugs

cURL


curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/users/:id \
    -d '{"role":"editor"}' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer <TOKEN>" \
    -X PATCH

Example Response


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

Remove Bucket User

Remove user 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 /v2/buckets/${YOUR_BUCKET_SLUG}/users/:id

cURL


curl https://api.cosmicjs.com/v2/buckets/${YOUR_BUCKET_SLUG}/users/:id \
    -H "Authorization: Bearer <TOKEN>" \
    -X DELETE

Example Response


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