comecerodocs
Users

Create a user

POST
/users

Adds a user who can sign in to your dashboard, in the mode of the token you call with. A user made with a test token is a test user and its user_id gets .test added. Fires the user:created event.

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

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Request Body

application/json
  1. body

A new user.

user_id*string

The sign-in name: at least 5 and up to 100 characters, made of letters, numbers, underscores, dashes and periods. It is stored in lower case. In test mode .test is added to the end if it is not there. 409 if it is taken.

Length5 <= length <= 100
name*string

The user's full name.

Lengthlength <= 75
email*string

The user's email address. It must not belong to another user of the account, test or live (409).

Formatemail
Lengthlength <= 100
password*string

The password, from 8 to 50 characters.

Formatpassword
Length8 <= length <= 50
language?string

A two-letter ISO 639-1 language code.

allow_test_transactions?boolean

True when the user may work in test mode. The default is true.

Defaulttrue
roles?array<string>

The role_id of each role to give the user. Each must exist (400).

permissions?array<>

Permissions to give the user directly.

meta?|

Your own data about the user, any JSON up to 2,048 characters.

Response Body

The new user.

application/json
  1. response

A person who can sign in to your dashboard. Users are kept per mode: test users and live users are separate, and a test user's user_id ends in .test. When a user signs in, they get a trusted token with the user's permissions.

object?"user"

The object type. Always user.

Value in"user"
url?string

The URL of this user.

Formaturi
user_id?string

The user's sign-in name, in lower case. A test user's ends in .test.

test?boolean

True for a test user.

date_created?string

When the user was created.

Formatdate-time
date_modified?string

When the user was last changed.

Formatdate-time
account_id?string

The account the user belongs to.

account_alias?|

The alias of your account, which users may sign in with instead of the account ID.

account_live?boolean

True when your account may take live payments.

name?string

The user's full name.

Lengthlength <= 75
email?string

The user's email address. Each user needs their own, across test and live users.

Formatemail
Lengthlength <= 100
is_account_owner?boolean

True for an owner of the account. The user who signed up is an owner.

language?|

The user's language, as a two-letter ISO 639-1 code in lower case.

locale?|

The locale of the user's browser, such as en-US, saved each time they sign in. Null until they first sign in.

date_last_login?|

When the user last signed in. Null if they never have.

Formatdate-time
allow_test_transactions?boolean

True when the user may work in test mode.

roles?array<string>

The role_id of each role given to the user.

permissions?array<>

The permissions given to the user directly. Where a role and a permission disagree, the more generous one wins.

effective_permissions?

What the token or user may really do, after its roles and permissions are combined and cut down to what its token type allows. Each key is a resource and each value says which methods are allowed on it.

meta?|

Your own data about the user, any JSON up to 2,048 characters.

formatted?

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

curl -X POST 'https://api.comecero.com/api/v1/users' \  -H 'Content-Type: application/json' \  -d '{  "user_id": "jane.smith",  "name": "Jane Smith",  "email": "jane@example.com",  "password": "correct-horse-battery"}'
Example Response
{  "object": "user",  "url": "https://api.comecero.com/api/v1/users/jane.smith.test",  "user_id": "jane.smith.test",  "test": true,  "date_created": "2026-10-01T14:36:52Z",  "date_modified": "2026-10-01T14:36:52Z",  "account_id": "AB1234",  "account_alias": "example-shop",  "account_live": true,  "name": "Jane Smith",  "email": "jane@example.com",  "is_account_owner": false,  "language": "en",  "locale": "en-US",  "date_last_login": "2026-11-06T09:12:40Z",  "allow_test_transactions": true,  "roles": [    "support"  ],  "permissions": [],  "effective_permissions": {    "orders": {      "create": false,      "read": true,      "update": true,      "delete": false    }  },  "meta": null}

List users GET

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

Get a user GET

Gets one user. A trusted token may always read its own user with `me`, even without the `users` read permission. Reading any other user needs a secret or trusted token with that permission. A user of the other mode is not found (`404`).