Groups and permissions

This page is for the developer managing your organisation's groups from another system.

It covers listing, adding, changing and deleting groups, setting the permissions each group holds, and the four permissions a connection may not give.

Before you start

Each person is in one group at most. What a person can do in InMyWords is decided by the permissions of their group.

1. Where to send calls. The base address is https://app.inmywords.chat/api/integrations/v1/
2. Send your key with every request. Authorization: Bearer imw_<64 hex characters>
3. The scopes you need. Reading needs groups:read. Adding, editing and deleting groups, and setting their permissions, need groups:write.
4. How values are written. Ids are strings of digits, such as "1842". Times are ISO 8601 in UTC. Field names are snake_case.
5. How answers are shaped. One item comes back as {"data": {...}}. A list comes back as {"data": [...], "next_cursor": "..."}, and next_cursor is null on the last page.
6. Reading a list. A list takes limit and cursor. limit is 50 by default and 100 at most, and a larger value is reduced to 100. Groups have no change time, so updated_since is not taken here and answers 400 invalid_request. A limit or cursor that cannot be read answers 400 invalid_request.
7. Retrying safely. A POST takes an Idempotency-Key header. The same key with the same body within 24 hours gives you the first result back. The same key with a different body answers 422 idempotency_key_reused.

Endpoints

What a group looks like

{
  "data": {
    "id": "57",
    "name": "Housing officers",
    "description": "Front-line housing advice.",
    "permissions": ["read_conversations", "manage_cases"],
    "require_two_factor": true,
    "allow_hide_templates": true,
    "member_count": 12,
    "created_at": "2026-03-11T14:55:02Z"
  }
}

Permissions

GET /permissions gives you this list with the names, so your system does not need to hard-code it.

A connection cannot give a group manage_users, manage_billing, manage_integrations or manage_groups. Those are given in InMyWords, by a person in your organisation. manage_groups is among them because a member of a group holding it can give the other three on the Groups page.

curl https://app.inmywords.chat/api/integrations/v1/permissions \
  -H "Authorization: Bearer imw_..."

{
  "data": [
    {"code": "manage_users", "name": "Manage users"},
    {"code": "read_conversations", "name": "Read conversations"}
  ],
  "next_cursor": null
}

List your groups

curl https://app.inmywords.chat/api/integrations/v1/groups \
  -H "Authorization: Bearer imw_..."

Add a group

Send a name, and if you want them, a description, permissions, require_two_factor and allow_hide_templates. The answer is 201 with the new group.

curl -X POST https://app.inmywords.chat/api/integrations/v1/groups \
  -H "Authorization: Bearer imw_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b9e4f1a-2c3d-4e5f-8a9b-7c6d5e4f3a2b" \
  -d '{"name": "Housing officers", "description": "Front-line housing advice.", "permissions": ["read_conversations", "manage_cases"], "require_two_factor": true}'

Change a group

Send any of name, description, permissions, require_two_factor and allow_hide_templates. Anything you leave out stays as it is. If you send permissions, it replaces the whole list.

curl -X PATCH https://app.inmywords.chat/api/integrations/v1/groups/57 \
  -H "Authorization: Bearer imw_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Housing and tenancy officers"}'

Delete a group

A group that holds cases cannot be deleted. The answer is 409 group_holds_cases, with the number of cases in the message. Move the cases to another group in InMyWords first.

The group's members keep their accounts and are left in no group. The answer is 204 with no body.

curl -X DELETE https://app.inmywords.chat/api/integrations/v1/groups/57 \
  -H "Authorization: Bearer imw_..."

Set a group's permissions

1. Replace the list. PUT /groups/{id}/permissions, with the body {"permissions": [...]}.
2. Add one. POST /groups/{id}/permissions, with the body {"code": "..."}.
3. Remove one. DELETE /groups/{id}/permissions/{code}.

Each gives you back the group's permissions after the change. A code that does not exist answers 422 unknown_permission.

curl -X PUT https://app.inmywords.chat/api/integrations/v1/groups/57/permissions \
  -H "Authorization: Bearer imw_..." \
  -H "Content-Type: application/json" \
  -d '{"permissions": ["read_conversations", "manage_cases", "view_statistics"]}'

curl -X POST https://app.inmywords.chat/api/integrations/v1/groups/57/permissions \
  -H "Authorization: Bearer imw_..." \
  -H "Content-Type: application/json" \
  -d '{"code": "view_tickets"}'

curl -X DELETE https://app.inmywords.chat/api/integrations/v1/groups/57/permissions/view_tickets \
  -H "Authorization: Bearer imw_..."

{
  "data": ["read_conversations", "manage_cases", "view_statistics"]
}

Rules on every change

1. Four permissions cannot be given. Any change that would give a group manage_users, manage_billing, manage_integrations or manage_groups answers 403 permission_not_grantable. That covers a new group holding one, a PUT or PATCH whose list includes one, and a POST of one.
2. They can be taken away. Removing one of those four from a group is allowed.
3. Somebody can always manage people. Your organisation always keeps at least one enabled person in a group that holds manage_users. Removing manage_users from the last such group, or deleting it, answers 409 last_people_manager.
4. Translation settings stay in InMyWords. A group's translation wording, formality and explanation level are set in InMyWords, not through the API.
5. Only your own groups. A group of InMyWords, or of another organisation, answers 404 not_found.
6. Every change is recorded. Each one is written on your organisation's audit trail under the connection's name.

Errors

Every error comes back as {"error": {"code": "...", "message": "..."}}.