Create Role

Beta

POST/v1/identity/roles

Idempotent with Idempotency-Key header. Learn more

Creates a custom role that can then be assigned to users in your account.

Roles created through the API are always owned by your account and have the type user. Returns a conflict error if a role with the same name already exists.

Permissions requiredValues:roles:create

The role behind your API key or agent must grant every one of these permissions.

include[]optional arrayenumValues:ownerowner.accountpermissions

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

namestring

Display name for the role, such as "Warehouse Manager".

Must be unique within your account.

permissionsoptional array of string

Permissions to grant, in {permission}:{action} format, such as customers:read.

The first half is a permission code such as customers or sales_orders, and the action must be one of create, read, update, or delete. List each action separately to grant more than one action on the same permission. A role created without any permissions grants no access until permissions are added.

idstring

Role ID.

objectstringenumValues:role

Resource type identifier.

namestring

Display name of the role.

Unique within the account.

typestringenumValues:adminuserscanner

The kind of role.

The type gates behavior that individual permissions do not cover, and some actions are reserved for a single role type.

admin: full administrative access. Sensitive areas such as API keys, billing, and third-party integrations are restricted to admins no matter what permissions another role holds.
user: a custom role tailored to a specific need, with its permissions defined explicitly. Roles created through the API always have this type.
scanner: the role used by shop-floor scanning stations, assigned automatically when a scanning-station user is created.
sales_rep: a role for sales representatives. Order analytics are scoped to the rep's own orders.
agent: a role assigned to an automated agent rather than a person.

ownerownerExpandablenullable

Provenance of this role.

System-owned roles are platform-provided defaults shared across all accounts and cannot be updated or deleted; account-owned roles are custom to your account.

objectstringenumValues:owner

Resource type identifier.

typestringenumValues:systemaccount

Where this resource came from.

system: a platform-provided default shared across all accounts; not editable.
account: created and owned by a specific account; the account field identifies which.

accountaccountExpandablenullable

The account that owns this resource.

Present only when type is account; system-owned resources have no owning account.

idstring

Account ID.

objectstringenumValues:account

Resource type identifier.

namestring

The account's display name.

default_billing_addressaddressnullable

The address billed by default on orders for this account.

Always returned as null in this endpoint.

default_shipping_addressaddressnullable

The address shipped to by default on orders for this account.

Always returned as null in this endpoint.

brandingaccount_brandingnullable

Customer-facing branding for the account, such as the logo, support contacts, and social links.

Always returned as null in this endpoint.

portalaccount_portalnullable

The account's customer portal settings, including the portal URL slug.

Always returned as null in this endpoint.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

permissionsarray of stringExpandablenullable

Permissions granted by this role, in {permission}:{action} format, such as customers:read.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

Responses

201

Successful response for Create Role

Create Role

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const role = await client.identity.roles.create({
  name: 'Warehouse Manager',
  permissions: ['customers:create', 'customers:read', 'customers:update', 'invoices:read'],
});

console.log(role.id);

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const role = await client.identity.roles.create({
  name: 'Warehouse Manager',
  permissions: ['customers:create', 'customers:read', 'customers:update', 'invoices:read'],
});

console.log(role.id);

201 example

{
  "id": "rl_3xknmfqflhvb",
  "object": "role",
  "name": "Admin",
  "type": "admin",
  "owner": {
    "object": "owner",
    "type": "account",
    "account": {
      "id": "ac_ykxoradjoeb3",
      "object": "account",
      "name": "Acme Inc.",
      "default_billing_address": null,
      "default_shipping_address": null,
      "branding": null,
      "portal": null,
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    }
  },
  "permissions": [
    "customers:create",
    "customers:read",
    "customers:update",
    "customers:delete"
  ],
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

{
  "id": "rl_3xknmfqflhvb",
  "object": "role",
  "name": "Admin",
  "type": "admin",
  "owner": {
    "object": "owner",
    "type": "account",
    "account": {
      "id": "ac_ykxoradjoeb3",
      "object": "account",
      "name": "Acme Inc.",
      "default_billing_address": null,
      "default_shipping_address": null,
      "branding": null,
      "portal": null,
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    }
  },
  "permissions": [
    "customers:create",
    "customers:read",
    "customers:update",
    "customers:delete"
  ],
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

Create Role

Authorization

Query Parameters

Request Body

Returns

Responses