Create a secret token
Creates a secret token for your server. The response is the only time you see the full token, so store it safely. Keep secret tokens on your server and never put one in a browser or an app.
The new token is live unless you send test=true in the query string. The mode of the token you call with does not decide it: a test token that leaves out test=true asks for a live token and gets 403.
Give the token only the permissions it needs. It needs at least one role or one permission, and the token you call with must hold every permission you ask for.
Secret and trusted tokens may call this with the auths create permission.
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
test?booleantrue makes a test token, false or no value makes a live token. Only a live token may create a live token.
falsebrowser_info?booleanWhen true, the response also has browser_info.
falsetimezone?stringAn IANA time zone name, such as America/New_York or UTC. It sets how date_start and date_end are read and the time zone of every date in the response. The default is the account's time zone (Settings, Technical), or UTC when it has none. A name that is not known is a 400.
application/json- body
The settings of a secret token. A new token needs at least one role or one permission. The token you call with must itself hold every permission you ask for (403 otherwise).
comments?|Your own label for the token, up to 250 characters.
length <= 250expires?|When the token stops working, in ISO 8601. It must be in the future. Leave it out for a token that never expires. On an update, send null or an empty string to remove the expiry.
date-timeroles?array<string>The role_id of each role to give the token. Each must exist (400).
permissions?array<>Permissions to give the token directly. Only resources and methods a secret token may have are accepted (403).
The new token, with the full token value.
application/json- response
An API token. The full token is shown only once, in the response that creates it. After that token holds a masked copy. A token's auth_id is the SHA-256 hash of the full token, so you can look a token up without sending it.
Test or live mode comes from the token. A token whose test is true reads and writes only test data, and a live token only live data. There is no test header. The test query parameter only counts when you create a token (such as POST /auths/secret or POST /auths/limited), where it picks the mode of the new token.
object?"auth"The object type. Always auth.
"auth"url?stringThe URL of this token.
uriauth_id?stringThe SHA-256 hash of the full token, in lower-case hex.
test?booleanTrue for a test token. A test token reads and writes only test data.
account_id?stringThe account the token belongs to.
account_alias?|The alias of the account the token belongs to.
type?stringThe token type. secret is for your server. trusted belongs to a signed-in dashboard user and is used in the browser. limited is used in the browser by shoppers. admin, app and service are used by Comecero itself and are not issued to integrators.
"secret""trusted""limited""admin""app""service"ip_address?|The IP address the token was issued to. Set for trusted and limited tokens, null for secret tokens.
token?stringThe full token in the response that creates it. Every other response gives a masked copy, such as secret.live.Kd4...9f2a. The full token starts with its type and its mode, for example secret.live. or limited.test..
expires?|When the token stops working. Null when it never expires. Trusted and limited tokens move this date forward each time they are used.
date-timeexpires_in_seconds?|Seconds until expires. Null when the token never expires.
date_last_used?|The day a secret token was last used, updated at most once a day. Null for other token types and for a token never used.
date-timecomments?|Your own label for the token, up to 250 characters.
length <= 250date_created?stringWhen the token was created.
date-timedate_modified?stringWhen the token was last changed.
date-timecustomer?|The customer a limited token was made for, as a URL, or the customer object when you send expand=customer. Only present on a token made for a customer.
user?|The user a trusted token belongs to, as a URL, or the user object when you send expand=user. Only present on a token tied to a user.
roles?array<string>The role_id of each role given to the token.
permissions?array<>The permissions given to the token directly.
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.
browser_info?Details about the caller's browser, read from the request headers. Only in the response that creates a token, and only when you send browser_info=true.
formatted?Display text for the dates. Only present when you send formatted=true.
curl -X POST 'https://api.comecero.com/api/v1/auths/secret' \ -H 'Content-Type: application/json' \ -d '{ "comments": "Order sync server", "permissions": [ { "resource": "orders", "methods": [ "read" ], "allow": true } ]}'{ "object": "auth", "url": "https://api.comecero.com/api/v1/auths/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "auth_id": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "test": true, "account_id": "AB1234", "account_alias": "example-shop", "type": "secret", "ip_address": null, "token": "secret.test.Hq7Zp2LkQ8rT1vWm3XyB6nCd9FgJ0sAe5uIo4hKl7Ec.1793887012.4b9e2d1c4e", "expires": null, "expires_in_seconds": null, "date_last_used": null, "comments": "Order sync server", "date_created": "2026-11-07T14:36:52Z", "date_modified": "2026-11-07T14:36:52Z", "roles": [], "permissions": [ { "resource": "orders", "methods": [ "read" ], "allow": true } ], "effective_permissions": { "orders": { "create": false, "read": true, "update": false, "delete": false } }}List token permission options GET
Lists the resources and methods a token of one type may be given. Use it to build a permissions form, or to check a request before you create a secret token. Send `type`: without it the list is empty. Any valid token may call this, including a limited token. No permission is needed.
Create a test trusted token POST
Swaps a live trusted token for a test trusted token with the same user and permissions. Use it when a signed-in user switches the dashboard or your own tool to test mode. You cannot ask for any other kind of trusted token. Trusted tokens are given to users when they sign in, not created through the API. Send `test=true` in the query string (`400` without it) and no request body (`403` with one). The token you call with must be a live trusted token (`403` otherwise). The new token lasts two hours from its last use.