Replace a role
Replaces a role with the one you send. This is PUT, not POST: send the whole role, including its role_id (400 without it) and at least one permission. Fields you leave out are cleared.
Secret and trusted tokens may call this with the roles update permission.
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
role_id*stringThe role's role_id.
application/json- body
A role and its permissions.
role_id?stringThe 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.
length <= 25name*stringThe role's name. Required when you create a role.
length <= 25comments?|Your own notes about the role.
length <= 150permissions*array<>The permissions the role gives. At least one is required.
1 <= itemsThe role.
application/json- 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.
"role"url?stringThe URL of this role.
urirole_id?stringThe 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?stringWhen the role was created.
date-timedate_modified?stringWhen the role was last changed.
date-timetest?booleanTrue for a test role.
account_id?stringThe account the role belongs to.
name?stringThe role's name.
length <= 25comments?|Your own notes about the role.
length <= 150permission_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.
curl -X PUT 'https://api.comecero.com/api/v1/roles/support' \ -H 'Content-Type: application/json' \ -d '{ "role_id": "support", "name": "Support", "comments": "Can look up orders and customers.", "permissions": [ { "resource": "orders", "methods": [ "read" ], "allow": true }, { "resource": "customers", "methods": [ "read" ], "allow": true } ]}'{ "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 } ]}