Managing integrations
Written for your organisation's administrator. How integrations are switched on, how a connection is made, how its keys are looked after, and where you can see what it has done.
This page is for the manager in your organisation who holds the Manage integrations permission.
It covers switching integrations on, accepting the integrations data policy, making a connection and choosing its scopes, looking after its keys, and revoking it.
Before the first connection
Integrations is an optional module, available on organisation plans only. InMyWords switches it on for your organisation, so ask support to switch it on.
- Find the Integrations page. It is under Organisation, and it is shown to people who hold the Manage integrations permission.
- Give somebody the permission. No group holds Manage integrations to begin with. A manager who can manage groups adds it to a group on Groups.
- Accept the integrations data policy. Before any connection can be made, somebody holding Manage integrations accepts it on the Integrations page. The acceptance is recorded with their name and the date.
The acceptance can be withdrawn on the same page. Withdrawing it stops every connection at once, and they work again when the policy is accepted again. When the policy changes, the new version has to be accepted before connections work again.
Adding a connection
- Open Add connection. It is the button at the top right of the Connections card, and it opens its own page.
- Give the connection a name. The name of the software it connects is a good choice.
- Choose its scopes. You can give a scope only if you hold the matching permission.
| Scope | Allows | Needs |
|---|---|---|
| Read conversations | List conversations, read one, its transcript and its facts. | Read conversations |
| Read summaries | Read a conversation's summary. | Read conversations |
| Read cases | List cases and read one. | Access to cases |
| Write cases | Create a case and start a conversation in it. | Access to cases |
| Send documents | Send a document in a case for translation. | Access to cases |
| Read documents | Read a document sent for translation and its translation. | Access to cases |
| Read people | List people and invitations, and read one. | Manage users |
| Manage people | Add, edit and remove people, withdraw an invitation, set a person's group. | Manage users |
| Read groups | List groups and the permissions they hold. | Manage groups |
| Manage groups | Add, edit and delete groups, and set a group's permissions. | Manage groups |
| Manage webhooks | Add, change and remove the connection's webhooks. | Manage integrations |
- Copy the key. When you save, the connection's key is shown once, on the page that answers the form. Copy it into the other software before you leave the page. InMyWords keeps no copy it can show you again: reloading the page does not show it again, and sending the form a second time makes nothing.
Keys
A connection holds at most two live keys. Each one is listed by its last four characters and when it was last used.
To replace a key without a gap, issue a new key, put it into the other software, then revoke the old one. A revoked key stops working at once.
- A new key is shown once, on the page that answers Issue a key, in the same way as the first.
- Issuing a key gives every scope the connection holds, so it needs the permissions those scopes need, as adding the connection did.
- A webhook's secret is shown once in the same way, on the page that answers Add webhook.
- Add webhook takes the address after a fixed
https://. Each event needs a read scope. Ticking an event the connection lacks the scope for gives the connection that scope when the webhook is added, and the page says so beside the event. An event whose scope you cannot give is shown but cannot be ticked. - Addresses. Where your organisation lists the addresses its people may reach InMyWords from, its connections are held to the same list.
The connection's page
The connection's page is in parts under Integrations in the sidebar: Overview (name, scopes, revoke), Keys, Webhooks, Deliveries and Calls.
| Card | Shows |
|---|---|
| Scopes | The scopes the connection holds. |
| Keys | Each key's last four characters, when it was issued and when it was last used. |
| Webhooks | Each webhook's address and events, and whether it is switched off. Send test sends it a signed test event now and says how the address answered. |
| Deliveries | Recent webhook deliveries, with status and duration. You can resend a delivery. |
| Calls | Recent calls, with time, method, address, status and duration. |
A webhook that has failed for three days is switched off, and the people holding Manage integrations are emailed.
Revoking a connection
Revoke, on the connection's page, stops the connection at once. Every key stops working and no webhook is sent.
A revoked connection is kept. The Integrations page lists it under Show revoked connections, and its own page says who revoked it and when.
The audit trail
Every change a connection makes, and every read of a conversation's words, is on your organisation's audit trail under the connection's name.
Every change to a connection, its keys and its scopes is on the audit trail under the name of the person who made it.
What a connection can never do
- Give a group Manage users, Manage billing, Manage integrations or Manage groups, or put a person in a group that holds one of them.
- Send a password reset.
- Remove a person's authenticator or passkeys.
- Erase a person.
- Start a conversation without a person.
- Leave your organisation with nobody able to manage people.