Authentication

A key is the string carom_sk_ followed by 43 letters, digits, dashes, and underscores. Create one in the Carom app under Settings › API keys. You give it:

• a name, up to 100 characters, so you can tell your keys apart;
• a tier, read or read/write, described under Read and write keys. The account’s API access setting limits which tiers you can create;
• an optional expiry, which must be in the future. A key without one works until it is revoked.

Carom shows the full key once, when you create it, and stores only a hash of it. The key list shows the first eight characters after carom_sk_ so you can match a key to where you use it. A lost key can’t be recovered: revoke it and create another.

Keys are managed only from a signed-in session in the app. The operations that create, list, and revoke keys refuse API keys, so one key can’t create another.

Send the key as a bearer token in the Authorization header of every request:

Authorization: Bearer carom_sk_…

The header is the only place Carom looks. A key in the query string or a cookie is ignored, and the request fails with 401 unauthorized.

The 401 message says which problem Carom found. Without an Authorization header, it is “Send an API key in the Authorization header as a Bearer token.” When the header holds a key that is unknown, revoked, or expired, or whose user or account no longer has access, it is “The bearer token is invalid, expired, or revoked.” The code is unauthorized in both cases.

Every key has one of two tiers. Each operation in this reference carries a badge saying which tier it needs.

The badge, not the HTTP method, decides. A few POST operations only read, such as Search and Create a download URL, and accept a read key. Generating a daily briefing and generating a meeting brief need a read/write key. A read key on a Write key operation gets 403 api_key_insufficient with the message “This endpoint requires a read_write API key.”

Retrieving a thread with a key doesn’t mark it read; the response shows the thread’s stored read state. To mark it read, use Mark a thread read.

Operations no key can call

Some operations accept only a signed-in session in the Carom app, whatever the key’s tier, and aren’t documented here:

• creating, listing, and revoking API keys;
• account settings, billing, and closing the account;
• connecting, changing, locking, and deleting mailboxes, and granting others access to them;
• inviting, changing, deactivating, reactivating, and deleting users;
• sending a draft;
• registering devices for push notifications, listing signed-in sessions, and the app’s launchpad and notification badge counts;
• accepting the terms of service, and signing in and out.

A key on one of these gets 403 api_key_insufficient with the message “This endpoint is not available to API keys.” Sending email is available only in the app, so a key can’t accept a proposal whose action sends an email; Carom answers 403 api_key_insufficient.

Account admins choose, in the Carom app, how much API keys can do in the account. The setting caps every key in the account, whatever its tier:

The setting doesn’t change the keys themselves. When an admin raises it again, each key can once more call what its tier allows.

You can’t create a key with a tier above the setting: while it is read, only read keys can be created, and while it is off, no keys can. Retrieve your key’s user reports the setting as account.api_access and the tiers your key’s user can create as capabilities.api_key_tiers.

A key acts as the user who created it, called your key’s user throughout this reference, and has exactly that user’s access. It sees that user’s personal contacts but not a colleague’s, threads from the mailboxes that user can read, and records shared with that user. This reference calls those records visible to your key. Operations limited to account admins, such as Agent configurations, work only when your key’s user is an admin.

A record your key’s user can’t see answers 404 record_not_found, the same as a record that doesn’t exist, so a key can’t learn that a hidden record exists. A record that user can see but not change answers 403 permission_denied.

The key follows the status of your key’s user:

• If your key’s user is deactivated or the account is closed, every request with the key gets 401 unauthorized.
• If your key’s user hasn’t accepted Carom’s current terms, requests get 403 terms_acceptance_required until that user signs in to the app and accepts them.

Because a key belongs to one user, an integration that needs to see everything a team has must use a key from a user who can see it. There is no account-wide key.

A key works until it passes its expiry or is revoked. Revoke a key in Settings › API keys. The user who created it can revoke it, and so can any account admin, who sees every key in the account.

Revoked and expired keys stay in the list, so you can still account for them. A request with one gets 401 unauthorized, the same as an unknown key.

The list shows when each key was last used. Carom records use at most once a minute per key, so the time answers whether a key is still in use rather than exactly when it last ran.