Create a role

POST/v1/roles

Creates a custom role from scratch or by duplicating an existing role.

Send permissions to build a role from scratch, or duplicate_of to copy another role's keys (you can add permissions to replace them). Custom roles are a Team feature; on Free this returns feature_locked.

Nobody can grant a key they do not hold: every key on the new role must be one you have yourself, or the call fails with permission_not_grantable. account.delete and ownership transfer belong to the Owner role only and can never be added. The change is audited. See Custom roles.

Send an Idempotency-Key header so a retried request never creates the role twice.

Permission: team.manage
Type: Write. Creates or changes data and writes an audit entry.
Auth: API key, MCP token or signed-in session
Capability: create_role
CLI: freeinvoiceautomation role create
Available: At launch, 1 January 2027

create_role

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/roles \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Bookkeeper",
  "permissions": [
    "businesses.view",
    "documents.view",
    "clients.view",
    "payments.view",
    "payments.record",
    "reports.view",
    "reports.export",
    "settings.view"
  ]
}'

{
  "data": {
    "id": "0193f31a-6c7d-7e8f-9a0b-1c2d3e4f5a6b",
    "name": "Bookkeeper",
    "preset_key": null,
    "permissions": [
      "businesses.view",
      "documents.view",
      "clients.view",
      "payments.view",
      "payments.record",
      "reports.view",
      "reports.export",
      "settings.view"
    ],
    "is_owner": false,
    "is_active": true,
    "created_at": "2027-01-08T14:00:00Z",
    "updated_at": "2027-01-08T14:00:00Z"
  }
}

Authorizations

Authorizationstringrequired

Bearer <api-key>. An API key from Settings > API keys, or an MCP token. See Authentication.

Headers

Idempotency-Keystring

Any unique string up to 255 characters. Required for API-key and MCP calls that create something; optional otherwise. See Idempotency.

Body

application/json

namestringrequired

Role name, unique in the account (case-insensitive).

permissionsstring[]

Permission keys for the role. Required unless duplicate_of is given.

duplicate_ofstring<uuid>

Copy the keys of this role.

Response

201 - application/json

idstring<uuid>

Id of the role.

namestring

Role name, unique in the account (case-insensitive).

preset_keyenum<string> | null

Which preset the role started as, or null for a custom role. Presets can be reset to default.

Available options: owner, admin, editor, viewer, accountant

permissionsstring[]

Permission keys (module.action) the role holds. See Permission keys.

is_ownerboolean

true only for the Owner role, which holds every key and cannot be edited or deleted.

is_activeboolean

false for custom and edited roles while the account is on Free after a downgrade. They are kept and come back on re-upgrade.

created_atstring<date-time>

When the role was created.

updated_atstring<date-time>

When the role last changed.

Errors

permission_not_grantable

feature_locked

validation_failed

conflict

idempotency_key_reused

Plus the common errors every call can return. See Errors.

Suggest edits Raise issue

List rolesPrevious Update a roleNext

create_role

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/roles \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Bookkeeper",
  "permissions": [
    "businesses.view",
    "documents.view",
    "clients.view",
    "payments.view",
    "payments.record",
    "reports.view",
    "reports.export",
    "settings.view"
  ]
}'

{
  "data": {
    "id": "0193f31a-6c7d-7e8f-9a0b-1c2d3e4f5a6b",
    "name": "Bookkeeper",
    "preset_key": null,
    "permissions": [
      "businesses.view",
      "documents.view",
      "clients.view",
      "payments.view",
      "payments.record",
      "reports.view",
      "reports.export",
      "settings.view"
    ],
    "is_owner": false,
    "is_active": true,
    "created_at": "2027-01-08T14:00:00Z",
    "updated_at": "2027-01-08T14:00:00Z"
  }
}