Users

User administration: creation, roles, DSP access and account status

Resource Overview

The user accounts of your organization: the owners of albums, tracks, artists and labels.

Base Endpoint
/users
Resource Type
users
User Scope
Your organization

Permissions

Requires the admin role. Scope: the users of your own organization.

Role You Assign Can Call the API Typical Use
admin Yes Another administrator for your organization
manager No Manages catalogue through the dashboard
label No A label that onboards its own artists
artist No Owns their own releases
analyst No Reads catalogue performance

Schema

Required Attributes

Field Type Validation Description
name string Required · up to 255 characters First name or full display name
email string Required · valid email · unique · up to 255 characters Sign-in address, unique across the platform
password string Required when creating · at least 8 characters, one uppercase · cannot be changed later Write-only, set once at creation — never returned in a response
role string Required · must be one of your assignable roles The role slug. Exactly one per user

Optional Attributes

Field Type Validation Description
lastname string Optional · up to 255 characters Family name
phone string Optional · up to 20 characters Contact number
provided-by string Optional · up to 255 characters Free-text origin of the account
is-disabled boolean Optional Blocks the account's access
fingerprint-dsp-allowed boolean Optional Whether the user may receive fingerprint DSPs
streaming-dsp-allowed boolean Optional Whether the user may receive streaming DSPs

Read-only Attributes

Field Type Description
id string Unique identifier
created-at datetime Creation timestamp
updated-at datetime Last modification timestamp

Relationships

Relationship Related Resource Description
white-label white-labels The organization the user belongs to
parent-user users The label that created this user. Read-only
dsps dsps The DSPs the user can distribute to

One role per user, written as a slug: "role": "artist". The roles you may grant come from GET /users/assignable-roles.

List Users

GET /users 
GET /users
Authorization: Bearer {token}
Accept: application/vnd.api+json

Query Parameters

Filtering

  • • filter[id] - One id, or several comma-separated
  • • filter[name] - Exact name, single value
  • • filter[names] - Comma-separated names
  • • filter[email] - Exact email, single value
  • • filter[emails] - Comma-separated emails
  • • filter[role] - Role slug
  • • filter[is-disabled] - true|false|1|0
  • • filter[created-at], filter[updated-at] - Dates

Other Parameters

  • • include - white-label, parent-user, dsps
  • • sort - name, lastname, email, created-at, updated-at
  • • page[number] - Page number
  • • page[size] - Results per page (default 20)

Example Request

GET /users?filter[role]=admin&filter[is-disabled]=false&sort=name

Success Response

200 OK 
{
  "data": [
    {
      "type": "users",
      "id": "887",
      "attributes": {
        "name": "Jane",
        "lastname": "Doe",
        "email": "jane@example.com",
        "role": "admin",
        "phone": null,
        "provided-by": null,
        "is-disabled": false,
        "fingerprint-dsp-allowed": true,
        "streaming-dsp-allowed": true,
        "created-at": "2026-03-11T09:20:00Z",
        "updated-at": "2026-07-30T14:05:00Z"
      },
      "relationships": {
        "white-label": {
          "data": { "type": "white-labels", "id": "3" }
        },
        "parent-user": {
          "data": null
        },
        "dsps": {
          "data": [
            { "type": "dsps", "id": "1" },
            { "type": "dsps", "id": "4" }
          ]
        }
      }
    }
  ],
  "meta": {
    "page": {
      "current-page": 1,
      "per-page": 20,
      "total": 309,
      "last-page": 16
    }
  }
}

Get User

GET /users/{id} 
GET /users/887?include=white-label,dsps
Authorization: Bearer {token}
Accept: application/vnd.api+json

Related Endpoints

  • • GET /users/{id}/white-label - The user's organization
  • • GET /users/{id}/parent-user - The label that created it
  • • GET /users/{id}/dsps - The DSPs it can distribute to

Create User

POST /users

Request Body

{
  "data": {
    "type": "users",
    "attributes": {
      "name": "Jane",
      "lastname": "Doe",
      "email": "jane@example.com",
      "password": "GENERATED_PASSWORD",
      "role": "artist"
    }
  }
}

Defaults When You Omit DSP Fields

A new user starts from your own account:

Field Default
dsps The DSPs assigned to your account
fingerprint-dsp-allowed, streaming-dsp-allowed Copied from your account

Each flag gates one family, so fingerprint-dsp-allowed: false yields your streaming DSPs only. You can only assign DSPs your own account holds; any other returns 422.

Success Response

201 Created 
{
  "data": {
    "type": "users",
    "id": "1204",
    "attributes": {
      "name": "Jane",
      "lastname": "Doe",
      "email": "jane@example.com",
      "role": "artist",
      "is-disabled": false,
      "fingerprint-dsp-allowed": true,
      "streaming-dsp-allowed": true,
      "created-at": "2026-07-30T16:45:00Z",
      "updated-at": "2026-07-30T16:45:00Z"
    },
    "relationships": {
      "white-label": {
        "data": { "type": "white-labels", "id": "3" }
      },
      "dsps": {
        "data": [
          { "type": "dsps", "id": "1" },
          { "type": "dsps", "id": "4" }
        ]
      }
    }
  }
}

Update User

PATCH /users/{id}

Request Body Example

{
  "data": {
    "type": "users",
    "id": "1204",
    "attributes": {
      "name": "Jane Marie"
    }
  }
}

To take an account out of service, send "is-disabled": true.

Success Response

200 OK 
{
  "data": {
    "type": "users",
    "id": "1204",
    "attributes": {
      "name": "Jane",
      "email": "jane@example.com",
      "role": "artist",
      "is-disabled": false,
      "updated-at": "2026-07-30T17:02:00Z"
    }
  }
}

Assignable Roles

GET /users/assignable-roles 
GET /users/assignable-roles
Authorization: Bearer {token}

Success Response

200 OK 
{
  "data": [
    { "slug": "admin", "name": "Admin" },
    { "slug": "manager", "name": "Manager" },
    { "slug": "label", "name": "Label" },
    { "slug": "artist", "name": "Artist" },
    { "slug": "analyst", "name": "Analyst" }
  ]
}

Errors

Status Meaning
401 Missing, expired or revoked token
403 You are not allowed to act on this user
404 No user with that id
422 Validation failed, or the request is not allowed for this user's current state
429 Rate limit exceeded — retry after the window in the response headers

Example

Assigning a DSP your own account does not hold: 

{
  "errors": [
    {
      "status": "422",
      "detail": "The following DSPs are not assigned to you: Beatport",
      "source": { "pointer": "/data/relationships/dsps" }
    }
  ]
}