API Clients (Outbound)

Outbound API Clients

An API client is an outbound connection — this platform calling another system's API. It is not related to the API keys that let other systems call you.

Where to find it

Architect Panel → Integration & Connections:

• API Clients — the outbound connections and their actions
• API Server — inbound access, which is a different thing entirely
• Data Sources — an alternative for reading external data

Architect Panel → Configuration:

• Site Settings — whether outbound calls are logged

The naming is genuinely confusing

"Client" here means this platform acting as a client of somebody else — the ordinary sense in HTTP, and the opposite of what many people expect from a screen called API Clients.

If you are looking for the credential a partner uses to reach you, that is an API key under API Server. This screen is for reaching outwards.

What a client defines

• A name.
• The host it calls and the protocol.
• Its authentication.

Beneath it sit actions — the individual calls, each with a path, an HTTP method and a request body.

Client and actions, not one call at a time

Connection details are configured once on the client, and each action reuses them. So a credential change is one edit rather than an edit per call, and the actions describe the API's operations rather than repeating its address.

When to use this rather than a data source

They overlap and the distinction is worth getting right:

• Data sources map an external system onto a datastore for reading, and optionally writing back — the right tool when you want the data to be in the platform.
• API clients call an operation and do something with the result — the right tool for actions rather than records: submit a job, trigger a notification, look something up in passing.

If your answer is "I want a table of their things", use a data source. If it is "I want to tell them something happened", use a client.

Credentials belong to the organisation

Register the connection under an account belonging to you rather than to an individual. An outbound integration that stops working because somebody left is an avoidable outage, and it is one of the commonest.

Consider what happens when the other end is down

You are now dependent on a system you do not control. Before wiring an outbound call into something time-sensitive, decide what should happen when it fails — retry, queue, degrade, or alert — because the default of "the action fails and somebody notices eventually" is rarely what you wanted.

Whose data is going out

An outbound call sends your data to somebody else. That is a processing decision as much as a technical one: know what each action transmits, satisfy yourself it is covered by your arrangements with that supplier, and prefer sending the minimum that works.

Worked example

An organisation configures one client for a courier's API, with three actions: book a collection, fetch a tracking status, and cancel. The credential is a service account the courier issued to the company. When the courier rotates it, one field changes and all three actions continue.

Recommendations

• Keep the inbound/outbound distinction clear in your own documentation.
• One client per external system, with actions beneath it.
• Use organisational credentials, never a person's.
• Decide the failure behaviour before going live.

Creating a Client and Its Actions

A client holds the connection; actions hold the calls. Configure in that order.

Where to find it

Architect Panel → Integration & Connections:

• API Clients — clients and their actions

Architect Panel → Configuration:

• Site Settings — outbound call logging, for commissioning

The client

Give it a name that identifies the external system, the host it calls, the protocol, and its authentication details. Everything beneath inherits these.

The actions

Each action is one operation:

• A name — what it does, in your language rather than theirs.
• A path, relative to the client's host.
• An HTTP method — GET, POST, PUT, DELETE or PATCH.
• A request body where the method takes one.

Name actions for what they achieve

"Book a collection", not "POST /v2/consignments". The path is already recorded in the action; the name is for the person deciding which action to call two years from now, who does not know the supplier's URL scheme.

Work from their documentation, and a real response

Build the action from the supplier's specification, then call it once and look at what actually comes back. Documentation describes the intended shape; the response tells you the real one, and they differ often enough that assuming is a poor bet.

Use their test environment

Most suppliers have one. Commission there, because a mistake against a live API is somebody else's real system — a test booking that becomes a real collection, a duplicate submission somebody has to unpick at their end.

Where there is no test environment, be correspondingly careful with the first live call and pick an operation that is easy to reverse.

Turn logging on to commission, and off afterwards

Outbound logging captures the full request and response, which is exactly what you need while getting an action right and exactly what you should not accumulate afterwards. See the logging article — it is the more important half of this.

Test the failure path

Call the action with something that will be rejected and see what happens. Most commissioning proves only the happy path, and the failure path is the one your support team will actually meet.

Keep secrets out of action definitions

Authentication belongs on the client, where it is handled as a credential. A token pasted into an action's path or body is a credential in a place nobody thinks to rotate.

Record what you built

Note which supplier, which environment, who owns the credential and where their documentation lives. Outbound integrations are consulted rarely and always urgently, and the person doing it is often not the person who built it.

Worked example

A team configures a client against a supplier's sandbox, builds three actions, and turns on outbound logging. The booking action fails until the logged response shows the supplier expects a date format their documentation did not mention. It is corrected, the failure path is tested with a deliberately invalid postcode, logging is turned off, and the client is repointed at production.

Recommendations

• Commission against a test environment.
• Build from a real response, not only the documentation.
• Name actions for what they achieve.
• Keep credentials on the client, never in an action.

The Outbound Log

Outbound calls can be logged. Unlike the inbound request log, this one stores the full request and response bodies.

Where to find it

Architect Panel → Configuration:

• Site Settings — Log outbound API client calls

Architect Panel → Integration & Connections:

• API Clients — the clients and actions being logged

Architect Panel → Security:

• Permissions — who can read the log

What is recorded

• The client and the action.
• The URL called and the headers sent.
• The full request body.
• The full response.

Why it needs the bodies

Because diagnosing somebody else's API requires them. A status code tells you a call failed; only the response tells you the supplier rejected a date format, or returned a success wrapper containing an error, or sent a field their documentation never mentioned.

Without the bodies, an outbound integration problem is a guessing exercise conducted through a supplier's support desk.

Which is exactly why it ships off

Full bodies mean the log contains whatever you send and receive — including personal data. An action submitting a customer's details logs those details in full, alongside the headers, which may include credentials.

This is a substantially more sensitive store than most logs, and it is easy to forget it is on.

Turn it on to debug, and off again

That is the intended pattern, and it is worth being disciplined about because nothing will remind you. Enable it while commissioning or investigating, get what you need, turn it off.

A log left on for a year against a busy integration is a large archive of personal data you never decided to keep.

If you must leave it on

Where an integration is genuinely unstable and needs standing visibility:

• Restrict who can read it to named administrators.
• Set a short retention — days, not months.
• Include it in your record of what personal data you hold.
• Diary a date to reconsider.

Mind the headers

Headers carry authentication. Anyone who can read this log can potentially read a credential for the supplier's system — so treat read access to it as equivalent to access to that credential, and rotate the credential if the log has been shared more widely than intended.

Take extracts, not screenshots

When sending evidence to a supplier's support team, send the specific exchange rather than a broad export, and check what is in it first. It is easy to send a customer's details to a third party's helpdesk while trying to demonstrate a formatting problem.

The inbound log is different

The inbound request log records metadata — key, datastore, method, outcome, row count, duration — and not bodies. It is safe to leave on permanently, and is. Do not reason about the two the same way.

Worked example

An integration starts failing intermittently. Outbound logging is enabled for an afternoon, and the captured responses show the supplier returning a rate-limit message inside a 200 response. The fix takes an hour, the extract sent to the supplier is trimmed to two exchanges with the customer name removed, and logging goes off the same day.

Recommendations

• On to debug, off afterwards — every time.
• Treat read access as credential access.
• Check extracts before sending them to a supplier.
• Never reason about it like the inbound log — it holds far more.