# Managing Users

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

<Callout type="info">
  User and access role management is available to **distributor accounts only**. The authenticated user must have the **`admin_user`** role.
</Callout>

## 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.

```ruby
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.

```ruby
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

```ruby
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

```ruby
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

```ruby
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"}, ...}]
```