SquidSupport
Product reference / Settings

API keys

In the app: Settings → API Keys

Needs the 'Manage API Keys' permission.

API keys let your own systems read data from Squid over the public API, without a person signing in. This page lists the keys of your organization and lets you create, rotate and revoke them. Each key has its own scopes, store boundary, optional IP allowlist and expiry. The "API reference" link at the top opens the technical documentation.

Rate limits

The "Rate limits" bar shows how many API requests per minute your plan allows; click it to see the table for every plan.

  • Starter: 60 reads, 20 writes, 10 sends.
  • Basic: 120 reads, 40 writes, 20 sends.
  • Pro: 300 reads, 100 writes, 50 sends.
  • Advanced: 600 reads, 200 writes, 100 sends.
  • Enterprise: 1200 reads, 400 writes, 200 sends.

The limits are per minute and per organization. Each request counts against the key that made it and against the organization as a whole, and creating more keys does not give more requests. A single key can consume the whole organization allowance. The allowance refills continuously; it does not reset all at once each minute. During a problem with the shared limiter, reads use a reduced allowance on each serving instance, so the usual shared ceiling does not apply in the same way. Everything the public API offers today is a read; writes and sends are listed because the response headers mention them.

Your own plan is marked "Your plan". That mark needs the 'Billing' permission; without it the table is shown without a mark.

When a request is refused for going over the limit, the response says how many seconds to wait before trying again. Follow that value.

Key list

Each row is one key:

  • "Key": its name, the first characters of the key (a prefix to recognise it by, not usable as a credential), when it was created, and when it expires with its lifetime in days, or "Never expires". An IP allowlist is listed underneath when the key has one.
  • "Scopes": what the key may read. Hover over a scope to see what it means.
  • "Stores": "All stores", or the stores the key is limited to.
  • "Status": "active", "expired", "revoked" or "disabled". Only an active key works. A revoked key shows the reason that was given.
  • "Last used": when the key last made a request, and from which IP address.
  • "Rotate" and "Revoke": shown for active keys only.

The secret of a key is never shown in this list. With no keys, the page shows "No API keys yet" and a "Create your first key" button.

An organization can have at most 5 active keys. At the limit, "Create key" is disabled and says so; revoke a key first. Rotating does not count, because it replaces a key.

A key's scopes, stores, allowlist and expiry cannot be changed on this page after creation. To change them, create a new key and revoke the old one.

Create key

"Create key" opens the "Create an API key" dialog.

"Name" is required, up to 255 characters. Name the key after the system that will use it. Use one key per integration: a shared key cannot be revoked without breaking every system that uses it, and the audit log records which key did what.

Then choose the scopes, the store boundary, an optional IP allowlist and the expiry; each is explained in its own section below.

"Your current password" is required for creating, rotating and revoking a key. It makes sure that someone who gets hold of an open browser session cannot create a key. A wrong password is shown under the field. Key changes allow up to 10 password checks per minute for your account from the same IP address. Requests beyond that limit are refused. Once the combined count of wrong passwords and refusals reaches five, a further request over the minute limit starts a 15-minute block. Five wrong passwords alone do not start that block. A successful password check clears the failure count.

"Create key" is available once the name, at least one scope and the password are filled in, the allowlist has no more than 20 entries, any custom expiry is accepted, and at least one store is ticked when "Selected stores" is chosen. After creating, the secret is shown once.

Scopes

A scope is one thing a key may read. Scopes do not include each other: tick exactly what the integration needs, and start narrow.

"Reads available today", each works on its own:

  • "brands:read": the list of stores the key can reach.
  • "metrics:read": CSAT and handle-time figures for a period. No message text.

"Bulk export", for copying data out in bulk:

  • "export:read": the bulk export itself. It carries a "Needs activation" badge: bulk export has to be switched on for your organization by Squid first, after the data-protection terms are in place. Until then a key with this scope cannot be created; the request is refused. Contact Squid support with your organization name and what the export is for. The same switch covers "returns:read" and "refunds:read", although they carry no badge: a key with either of them cannot be created before bulk export is switched on. If bulk export is switched off again later, keys that already have these scopes stop working for exports.
  • "tickets:content:read": subjects and the messages customers can see.
  • "customers:pii:read": customer name, email address and phone number.
  • "tickets:notes:read": adds internal notes to exported messages.
  • "returns:read": return requests with their items.
  • "refunds:read": refunds with exact amounts.

Exporting tickets and messages needs "export:read", "tickets:content:read" and "customers:pii:read" together. Exporting returns or refunds needs "export:read" with "returns:read" or "refunds:read". The dialog warns about missing ticket-export scopes and offers "Add the missing scopes", unless "returns:read" or "refunds:read" is also selected. In that case, check the ticket-export requirements yourself. "export:read" alone can read records identifying deleted tickets and messages, so an incomplete ticket-export combination does not block that feed. The other export scopes reach nothing without "export:read".

Store boundary

  • "Every store": the key reaches all stores of the organization, including stores added later. This is the default.
  • "Selected stores": the key reaches only the stores you tick. Stores added later are not included. Choosing stores needs the 'View Brands' permission.

Lists and exports include only stores inside the boundary. Asking directly for an excluded store answers as if the store does not exist.

If your own account is limited to certain stores, a key you create is limited to those stores too. You cannot include a store you cannot see, and you cannot rotate a key that reaches every store or includes any store outside your own access. With no store access, you cannot create or rotate a key.

IP allowlist and expiry

"IP allowlist" is optional. Enter the networks the key may be used from, one per line, IPv4 or IPv6, at most 20. A request from any other address is refused the same way as an unknown key. Leave it empty to allow any address.

"Expiry" has three options:

  • "90 days (default)".
  • "Custom": 1 to 365 days. Enter a whole number; if you enter a fraction, the form drops the fractional part before saving.
  • "Never expires".

An expired key stops working at that moment and shows "expired". Rotating a key does not extend it: the replacement keeps the original expiry. When a key runs out, create a new one.

The secret is shown once

After "Create key" or "Rotate key", a dialog shows the secret: "Copy your new API secret now" or "Copy the replacement API secret now".

This is the only time the secret can be seen. Squid stores only a scrambled form of it and cannot show it again, send it again or recover it, and neither can Squid support. If it is lost, rotate the key and replace it everywhere.

  • "Reveal" and "Hide" show or mask the secret.
  • "Copy" copies it to the clipboard, also while it is masked.
  • Tick "I have stored this secret somewhere safe. I understand it cannot be shown again." to enable "Done". The dialog cannot be closed before that.

The integration sends the secret as a bearer token with each request.

Rotate

"Rotate" replaces a key's secret. Use it on a schedule, or when a secret may have leaked.

The "Rotate this key?" dialog asks for your current password and an optional "Reason", up to 2,000 characters, which is recorded with the old key. After "Rotate key":

  • the old secret stops working at once. There is no period in which both work, so plan the change in your integration around that;
  • the new secret is shown once;
  • the replacement keeps the scopes, store boundary, IP allowlist and expiry of the old key. Rotating is not a renewal.

In the list, the old key shows as revoked and the replacement as active.

Revoke

"Revoke" switches a key off for good. The "Revoke this key?" dialog asks for your current password and an optional "Reason", up to 2,000 characters, which is shown under the key's status afterwards.

After "Revoke key", the next request with that key is refused. This cannot be undone and the key cannot be brought back. If something still depends on the key, create a replacement first. The revoked key stays in the list as a record.