Connecting a workflow tool to a register

A workflow tool such as Zapier, Make or n8n can write rows into a register without anyone opening Alchex. It does this with an API key that belongs to your workspace, not to a person. This page is for the person setting that up.

Create a key

1. Open Settings → General and find API keys.
2. Create a key and give it a name you will recognise in the register's history, such as "Zapier — new customers". The name is what Alchex shows as the sender of every row that key adds.
3. Give it only the permissions it needs:
   • registers:rows:add — may add rows.
   • registers:rows:change — may change an existing row.
4. Copy the key when it is shown. You cannot see it again; create a new one if it is lost.
5. Put the key in a team: see Choose the teams a key works in. A new key is in no team, so it reaches nothing until you do.

Only a workspace admin can create keys. A key can add and change rows. It cannot archive or delete one, and it cannot touch anything but register rows.

Choose the teams a key works in

A key works only in the teams you put it in, with a team role, just like a person:

• Viewer — may list the team's registers and their columns, but not add or change rows.
• Author or Admin — may also add and change rows in the team's registers, as far as the key's permissions allow.

What a key may do is its permission and its team role: a key with registers:rows:add that is only a viewer in a team cannot add rows there. A key is never a workspace admin, whatever its team roles.

In Settings → General → API keys, each key in the list has a Teams button. Add a team, pick the role, and save. Remove its last team and the key reaches nothing again. A key in no team is marked Needs a team; keys made before teams existed start that way, so put each one back in the teams it should serve.

A register in a team the key is not in answers 404, exactly as if it did not exist, so a key never learns the names of another team's registers.

The four addresses

Send the key as Authorization: Bearer <key> and a JSON body. All addresses start with /api/v1/registers on your Alchex address. A register is named by its id, its code or its name.

Read the columns first: a row is a set of cells, keyed by column name.

{ "rows": [ { "cells": { "Customer": "Acme", "Risk": "High" }, "quote": "Email from Acme, 3 Nov" } ] }

• At most 50 rows in one request. The optional quote says where the row came from.
• A field the API does not know is refused, not ignored, so a typo shows up in the tool's log.
• Changing a row sends only the cells to change: { "cells": { "Risk": "Low" } }.
• A reply in plain words says what went wrong. 400 is a request to fix, 401 a missing or invalid key, 403 a key without the permission, 404 a register or row that is not there.

Sending the same thing twice is safe

Workflow tools retry. Add an Idempotency-Key header with a value that is the same for the same event and different for different ones, such as the id of the record in the tool that triggered the run. A repeat with the same key does not add the rows again: it answers 200 with replayed: true and the ids of the rows from the first time.

The rate limit

A key may make 60 requests a minute. Past that the answer is 429 with a Retry-After header saying how many seconds to wait; most workflow tools retry on their own. Sending several rows in one request, rather than one request per row, keeps you well inside it.

Do the rows go in live, or as suggestions?

By default rows from an API key arrive as suggestions: they wait in the register for someone to accept them, and nothing in the table changes until then. See Suggested and confirmed. The request still succeeds, with 202.

To let a trusted workflow write straight into the table, open the register, open Properties and turn on Accept rows from API keys straight in. Turn it off and new rows go back to being suggestions; rows already added stay.

• The switch belongs to one register, so a key you trust for one table does not reach the others live.
• Only a workspace admin, or an admin of the team that owns the register, can change it. Everyone else sees the switch but cannot move it, with the note "Only an admin can change this."
• The register's history records who turned it on or off.

Is the key being used?

Settings → General → API keys lists every key with its teams and when Alchex last received a request from it. Use it to check a new workflow is reaching Alchex, or to find a key nobody uses any more and remove it.

The time can be up to a minute old: Alchex notes a key at most once a minute. The list is visible to admins only. "Never used" means just that, so check the key, its teams and the address. If the list says some keys may be missing, Alchex could not reach the key service just then; the keys it shows can still be moved between teams.