Managing API keys

An API key is a secret string that lets one of your systems act on the API on your firm's behalf. This page covers where API keys live, how to create one (and copy it safely the one time it is shown), what each setting on a key controls, and how to revoke a key you no longer trust.

If you are new to the API, start with The Esqase API for what it is and what it is for.

Before you begin

• API keys live under Settings, in a new Developers group, on the API keys page (/settings/developers).
• Creating and revoking keys is owner and administrator only. By default, the Attorney and Staff roles have no access to API keys. A firm owner can grant the new API keys permission to another role from the Roles and permissions grid (it lives under a Developers group there). If your role does not include it, the API keys card and page will not appear for you.
• A key always acts as the person who created it. Whatever that member is allowed to do in the app sets the ceiling for what the key can do. Create keys under an account that has the access the integration genuinely needs, and no more.

Open the API keys page

1. In the sidebar, click Settings.
2. Under the Developers group, click API keys.
3. The page lists every key your firm has created, with a row for each.

If your firm has not created any keys yet, the page shows an empty state ("No API keys yet") with a button to create your first one.

Read the keys table

Each row in the table describes one key:

• Name: the label you gave the key so you can tell your keys apart (for example, "Intake sync" or "Migration script").
• Key: a masked preview, shown as the key's prefix, an ellipsis, and its last four characters (for example, esq_ab12cd…wxyz). The full key is never shown here. This preview is only there to help you match a row to a key you have stored elsewhere.
• Scopes: the kinds of data the key may touch and whether it may read, write, or both (for example, "Contacts: Read" or "Matters: Read, Write"). See Authentication and scopes.
• Allowed domains: the web domains a key is restricted to, so it only works from those sites in a browser. It shows Any when the key is not restricted to any domain (the default). See Authentication and scopes.
• Status: one of Active (working), Revoked (turned off by someone), or Expired (past its expiry date). Only Active keys work.
• Last used: when a request last came in using this key, or a dash if it has never been used.
• Expires: the date the key stops working, or a dash if it never expires.
• Created by: the member who created the key (and therefore whose access the key inherits).

The table is paginated, so if you have many keys, use the Previous and Next buttons beneath it to move through pages.

Create an API key

1. On the API keys page, click Create API key.
2. In the dialog, fill in:
   • Name (required): a short label for the key. Pick something that tells you what the key is for, since you will see it in the table and in your audit log.
   • Scopes (at least one required): a checklist of what the key may do, grouped by Contacts, Matters, Leads, Practice areas, and Matter types. Each group has a Read box and a Write box. Tick only what the integration needs: a key that just imports contacts needs Contacts: Write, while a key that mirrors your case list elsewhere might need only Matters: Read. See Authentication and scopes for what each scope allows.
   • Expires (optional): a date after which the key automatically stops working. Leave it blank for a key that never expires. An expiry date is a good safety net for keys handed to a contractor or used for a one-time migration.
   • Allowed domains (optional): a textarea where you list the web domains allowed to use this key from a browser, one hostname per line or comma-separated (for example, app.example.com, *.example.com). Leave it empty to allow any domain. This only restricts requests made from a web page: server-to-server calls (curl, Postman, a backend integration) are never affected, since those send no browser origin. See the "Restricting a key to certain domains" section of Authentication and scopes for how enforcement works.
3. Click Create API key.

Copy the key, once

When you create a key, Esqase shows you the full key exactly once, on a "copy your API key" screen. It starts with esq_ followed by a long random string.

1. Click the copy button next to the key to copy it to your clipboard.
2. Paste it straight into wherever your integration stores secrets (an environment variable, a secrets manager, your script's config). Do not save it in a plain document or email it.
3. When you have stored it safely, close the dialog.

Once the dialog closes, the new key appears in the table with an Active status and its masked preview.

Edit a key's allowed domains

You can change the list of allowed domains on an Active key at any time, without creating a new key.

1. On the API keys page, find the key in the table.
2. In its row, click the Domains button.
3. In the "Edit allowed domains" dialog, adjust the list (one hostname per line, or comma-separated). Leave it empty to allow any domain.
4. Click Save.

A key's scopes and expiry are fixed when the key is created and cannot be changed afterward, but the allowed domains list can be edited whenever you need to (for example, to add a new site or lock a key down after it has leaked into a page it should not be on). The change is recorded in your firm's audit log as an update to the key.

Revoke an API key

Revoking a key turns it off for good. Use it when a key is no longer needed, when a contractor's engagement ends, or if you suspect a key has leaked.

1. On the API keys page, find the key in the table.
2. In its row, open the ... (more) menu and click Revoke.
3. Confirm in the dialog that appears.

The key's status changes to Revoked and it stops working immediately: the very next request that uses it is rejected. Revoking cannot be undone. If you need that integration again, create a new key.

Common questions

• Where do I get the key string? Only on the "copy your API key" screen, the one time it is shown right after you create the key. After that, the table shows only a masked preview.
• I lost my key. Can I see it again? No. Esqase stores only a scrambled version. Revoke the lost key and create a new one.
• Why can't I create a key? Creating keys is owner and administrator only by default. If you are an attorney or staff member, ask a firm owner, or have them grant the API keys permission to your role.
• What can a key actually do? Two limits apply at once: the scopes you ticked, and the access of the member who created it. A key can never exceed either. See Authentication and scopes.
• Can I limit which sites use a key? Yes. Set Allowed domains on the key (in the create dialog, or later with the Domains button). A key with an allowlist only works from those domains when it is called from a browser, and requests from any other domain are blocked. It does not affect server-to-server calls (curl, Postman, a backend integration), since those send no browser origin.
• Does an expired key delete my data? No. Expiry (and revocation) only stops the key from working. Records it already created stay exactly where they are.

Related

• The Esqase API
• Authentication and scopes
• API resources and endpoints
• Roles and permissions
• Activity timelines and audit logs