Authentication and keys

Create a key#

Keys are created in your CoreSync admin by someone allowed to edit settings.

1. Open API access

   Sign in to your admin and go to Settings → API access. You need the permission to edit settings (SYSTEM:SETTINGS:EDIT). With only view rights you can see keys but not create them.

2. Click New key

   Name: who will use it, for example amani-crm. The name is shown as the actor on everything the key does, on the subscriber's timeline.

   What it may do: tick the scopes it needs (see Scopes). A scope you can't grant is greyed out with “You do not have the permission behind this scope.”

   Expires (optional): the key stops working at the end of that day. Requests per minute: leave it empty for 120, or set 1 to 6000.

3. Copy the key

   Click Create key. The key appears once, under “Copy your key now”. CoreSync keeps only a fingerprint of it, so nobody can show it to you again. If you lose it, create a new one.

The same page shows the base URL and the spec, and lists each key with its first characters and last four, its scopes, who created it, and when and from which IP address it was last used.

Send the key#

Put the key in the X-API-Key header of every request. A key is cs_live_ followed by 40 letters and digits.

curl https://coresyncapi.avitechcloud.com/api/v1/account \
  -H "X-API-Key: $CORESYNC_API_KEY"

When the key isn't accepted, the answer is 401 with one of these codes:

Scopes#

A key holds one or more scopes. They decide which operations it may call.

• write does not include read. A key that writes nearly always needs read too, to find what to change.
• A key without the scope gets 403 insufficient_scope, before its request body is even read.
• Give each key only the scopes it needs. A support bot that answers questions needs read and nothing else.

A key never does more than its creator#

Each operation also names the CoreSync permission behind it (x-required-permission in the spec). On every call, CoreSync checks that the person who created the key holds that permission in their role right now. If they don't, the answer is 403 key_owner_lacks_permission. Where two are listed, either one is enough.

• When someone's role changes, their keys follow within about 30 seconds.
• If the creator is deactivated, their keys can't do anything except GET /account. Revoke them and create new ones.
• When you create a key, you can only grant scopes backed by permissions you hold yourself.
• Everything a key changes shows on the subscriber's timeline under the key's name.
• If your ISP requires a manager's approval to suspend a subscriber whose subscription is still running, a key's suspension is filed as an approval request under the key's creator, and the API answers 202.

Your ISP's data only#

A key belongs to the ISP whose admin created it, and every call acts on that ISP. Nothing in a request can change that.

• A record that belongs to another ISP answers 404, exactly as if it didn't exist.
• If your CoreSync account is suspended or cancelled, its keys stop with 403 tenant_suspended. A terminated account answers 403 tenant_terminated.

Rotate a key#

Keys can't be changed after they're made, so rotating means replacing.

1. Create the new key

   Give it the same scopes and a name that tells the two apart.

2. Deploy it

   Put the new key wherever the old one is used.

3. Watch the old one go quiet

   On Settings → API access, the old key's “Last used” time stops moving.

4. Revoke the old key

   See below.

Rotate when someone who handled the key leaves, on a schedule (an expiry date does this for you), and at once if the key may have leaked.

Revoke a key#

On Settings → API access, click Revoke next to the key and confirm. Anything using the key stops working immediately, and its requests get 401 api_key_revoked. This can't be undone.

Revoked and expired keys stay listed under “Revoked and expired”, with who revoked them and when.

Keep keys secret#

• Keep keys in a secret manager or an environment variable. Never in code, and never in git.
• Use one key per integration, so you can revoke one without breaking the others.
• Don't paste keys into chats, tickets or emails.
• Set an expiry date for short jobs and for contractors.
• Check “Last used” and its IP address now and then. A key used from somewhere unexpected should be revoked.
• Keys start with cs_live_ so you, and secret scanners, can spot one in a log or a repository. If you find one, revoke it.

Platform keys#

Avitech staff have their own platform keys (cs_plat_) for running CoreSync itself. They aren't covered here, and nothing on these pages needs one.