Tutorials

Managing Users

Copy page

This tutorial covers user creation with role assignment, updating user metadata, and managing access roles independently.

Create a user with roles

Users created without roles receive a "Custom Role" with minimal permissions. To provision a functional user, include an access-roles relationship in the creation request.

Code
response = RestClient.post(
  "https://api.idol.io/api/v2/users",
  {
    "data": {
      "type": "users",
      "attributes": {
        "login": "jsmith",
        "email": "jsmith@example.com",
        "name": "Smith",
        "first-name": "John",
        "skip-invitation": false
      },
      "relationships": {
        "group": {
          "data": { "type": "groups", "id": "42" }
        },
        "access-roles": {
          "data": [
            {
              "type": "access-roles",
              "attributes": { "name": "admin_user" }
            }
          ]
        }
      }
    }
  }.to_json,
  "Authorization": "Bearer <token>",
  "Content-Type": "application/vnd.api+json"
)

login and email are immutable after creation. An invitation email is sent automatically unless skip-invitation is true.

Available role names

Name	Description
admin_user	Full administrative access
trends	Access to trend analytics
catalog_management	Catalog editing and management

A user can hold multiple roles simultaneously.

Update user metadata

name (last name) and first-name can be updated at any time via PATCH /users/:id. login and email cannot be changed.

Code
response = RestClient.patch(
  "https://api.idol.io/api/v2/users/123",
  {
    "data": {
      "type": "users",
      "id": "123",
      "attributes": {
        "name": "Smith",
        "first-name": "Jonathan"
      }
    }
  }.to_json,
  "Authorization": "Bearer <token>",
  "Content-Type": "application/vnd.api+json"
)

Add an access role to an existing user

Code
response = RestClient.post(
  "https://api.idol.io/api/v2/access-roles",
  {
    "data": {
      "type": "access-roles",
      "attributes": { "name": "trends" },
      "relationships": {
        "user": {
          "data": { "type": "users", "id": "123" }
        }
      }
    }
  }.to_json,
  "Authorization": "Bearer <token>",
  "Content-Type": "application/vnd.api+json"
)

role_id = JSON.parse(response)["data"]["id"]

The response includes the new access-role resource with its id, needed to remove the role later.

Remove an access role

Code
RestClient.delete(
  "https://api.idol.io/api/v2/access-roles/#{role_id}",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/vnd.api+json"
)

Returns 204 No Content on success.

List a user's current roles

Code
response = RestClient.get(
  "https://api.idol.io/api/v2/users/123?include=access-roles",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/vnd.api+json"
)

roles = JSON.parse(response)["included"].select { |r| r["type"] == "access-roles" }
// => [{"id"=>"1", "type"=>"access-roles", "attributes"=>{"name"=>"admin_user"}, ...}]