comecerodocs
Roles

Create a role

POST
/roles

Creates a role in the mode of the token you call with. Give it to users and secret tokens through their roles list.

Secret and trusted tokens may call this with the roles create permission.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Request Body

application/json
  1. body

A role and its permissions.

role_id?string

The ID for a new role, up to 25 characters of letters, numbers, underscores, dashes and periods. Leave it out to make one from the name. 400 if it is taken. When you replace a role, it is required and must match the URL.

Lengthlength <= 25
name*string

The role's name. Required when you create a role.

Lengthlength <= 25
comments?|

Your own notes about the role.

Lengthlength <= 150
permissions*array<>

The permissions the role gives. At least one is required.

Items1 <= items

Response Body

The new role.

application/json
  1. response

A named set of permissions that you give to users and secret tokens. Roles are kept per mode: a test token sees only test roles.

object?"role"

The object type. Always role.

Value in"role"
url?string

The URL of this role.

Formaturi
role_id?string

The role's ID. You may choose it when you create the role. Otherwise it is made from the name, in lower case with dashes for spaces.

date_created?string

When the role was created.

Formatdate-time
date_modified?string

When the role was last changed.

Formatdate-time
test?boolean

True for a test role.

account_id?string

The account the role belongs to.

name?string

The role's name.

Lengthlength <= 25
comments?|

Your own notes about the role.

Lengthlength <= 150
permission_type?|

An older label kept for roles that have one. Comecero does not use it.

permissions?array<>

The permissions the role gives.

formatted?

Display text for the dates. Only present when you send formatted=true.

Example Request
curl -X POST 'https://api.comecero.com/api/v1/roles' \  -H 'Content-Type: application/json' \  -d '{  "name": "Support",  "comments": "Can look up and update orders and customers.",  "permissions": [    {      "resource": "orders",      "methods": [        "read",        "update"      ],      "allow": true    },    {      "resource": "customers",      "methods": [        "read"      ],      "allow": true    }  ]}'
Example Response
{  "object": "role",  "url": "https://api.comecero.com/api/v1/roles/support",  "role_id": "support",  "date_created": "2026-10-01T14:36:52Z",  "date_modified": "2026-10-01T14:36:52Z",  "test": true,  "account_id": "AB1234",  "name": "Support",  "comments": "Can look up and update orders and customers.",  "permission_type": null,  "permissions": [    {      "resource": "orders",      "methods": [        "read",        "update"      ],      "allow": true    },    {      "resource": "customers",      "methods": [        "read"      ],      "allow": true    }  ]}

List roles GET

Lists the roles of your account in the mode of the token you call with. The list is offset-based. Secret and trusted tokens may call this with the `roles` read permission.

Get a role GET

Gets one role. A role of the other mode is not found (`404`). Secret and trusted tokens may call this with the `roles` read permission.