Authentication
Your connection sends its key with every call. This is how to send it, replace it, stop it and keep it safe.
This page is for the developer whose system calls InMyWords, and for the person in your organisation who looks after its keys.
It covers the key every call carries, the answers when a key is refused, and how to replace, revoke and store a key.
The key
A key is imw_ followed by 64 lowercase hex characters, 68 characters in all.
- It belongs to a connection. A connection belongs to your organisation, not to a person.
- It is shown once, when it is made. InMyWords keeps only a hash of it and its last four characters. The Integrations page shows those four, so you can tell two keys apart.
- It carries the connection's scopes. If you change the scopes on the Integrations page, every key of that connection can do what the new scopes allow from the next call.
Sending it
Every call sends the key as a bearer token:
curl https://app.inmywords.chat/api/integrations/v1/me \
-H "Authorization: Bearer imw_3f9a0c2e7b1d4a6f8e0c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a"The same header works for the REST interface (https://app.inmywords.chat/api/integrations/v1/) and for SCIM (https://app.inmywords.chat/api/integrations/scim/v2/).
Only HTTPS is answered. A key sent in the address, in a cookie or in the body is not read.
When a key is refused
| Status | Code | Cause |
|---|---|---|
| 401 | unauthorised | there is no Authorization header, the header is not Bearer imw_ and 64 hex characters, or the key does not exist, has been revoked or belongs to a revoked connection |
| 403 | module_off | the Integrations module is off for your organisation, or your organisation has not accepted the current integrations data policy |
| 403 | ip_not_allowed | your organisation enforces a list of the addresses it may be reached from, and the call came from another |
| 403 | scope_missing | the key is valid, but the connection does not hold the scope the call needs |
| 429 | rate_limited | 60 calls from this address were refused 401 this minute; every call from it waits for the next minute |
{
"error": {
"code": "unauthorised",
"message": "The key is malformed or revoked."
}
}A missing Authorization header answers "No key was sent: the Authorization header is missing." A key that is wrong answers "The key is malformed or revoked." Both are 401 unauthorised.
If your organisation lists the addresses its people may reach InMyWords from, its connections are held to the same list. Ask for the addresses your calling system sends from to be added.
Replacing a key
A connection can hold at most two live keys, so you can change over to a new key without a gap.
- Make a second key on the connection's page in your organisation's Integrations section. It is shown once, on the page that answers Issue a key. Reloading that page does not show it again or make another.
- Put the new key in your calling system.
- Check the new key works with
GET /me. - Revoke the old key on the connection's page. The page shows when each key was last used.
A third key cannot be made while two are live. Revoke one first.
Stopping a key or a connection
- Revoking a key stops it at once. The connection's other live key keeps working.
- Revoking a connection stops every key of it at once. Its webhooks are no longer sent.
- Revoking cannot be undone. A revoked key or connection cannot be restored, so make a new one.
If your organisation withdraws its acceptance of the integrations data policy, or InMyWords switches the module off, every connection of your organisation stops at once and answers 403 module_off. Keys are not revoked by this. They work again once the policy is accepted and the module is on.
Keeping a key safe
- Store it with your other secrets. Keep the key where your calling system keeps its other secrets, not in source code.
- If it may have been seen, replace it. Revoke a key that somebody else may have seen, and make a new one.
- It is marked. Every key starts
imw_, so secret scanners can find it in code and logs.