Register and test
Dashboard steps for registering a source, the dry run that debugs your signature check, and why enabling is a separate, Owner-only act.
Registering a source is a dashboard job, at agent.useassistive.com/settings/context.
Your application cannot do it — there's no public API for managing sources, by design.
1. Register the source
Owners and Admins. You declare:
| Field | Notes |
|---|---|
| Name and description | Agents see these. Write them for the person running the lookup — "Shipment status", not "svc-logistics-v2". |
| Method | GET or POST. |
| URL template | e.g. https://api.acme.com/shipments/{shipment_id}. HTTPS, public. |
| Parameters | Name, type, required. The agent types the values. |
| Field map | Dotted JSON paths → labels. What agents actually see. |
| Custom headers | Optional static headers. Agents never see these. |
| Timeout | Default 5s, hard cap 10s. A larger value is silently clamped. |
Two things happen when you save:
- The signing secret is minted. This is one of the moments you can see it — copy it into your server's secrets now. See the signing secret.
- The source is created disabled. It cannot be used by agents yet. That's deliberate — see step 3.
2. Test it
Owners and Admins, and — this is the important part — the dry run works while the source is still disabled.
So the loop is: register, test, fix, test, and only switch it on once it actually works. You never have to expose a half-working source to your agents in order to debug it.
A dry run returns everything about the call we made:
- the resolved URL (your template with the parameters substituted in);
- the exact timestamp and signature we sent;
- the literal
signed_payloadthose were computed over; - every header we sent;
- the upstream status code;
- which mapped fields resolved.
Nothing is persisted.
signed_payload is the tool that tells you why verification is failing
When a signature check fails, it is almost always because your server built a different canonical string than we did — a missing trailing dot, a dropped query string, a re-serialized body.
signed_payload is the literal string we hashed. Log the string your server builds, run a
dry run, and put the two side by side. You'll see the difference immediately, instead of
reasoning about what it might be.
This turns the worst kind of bug — an opaque 401 with no detail — into a one-minute diff.
Reach for it early rather than after an hour of guessing.
The dry run also tells you whether your field map is right: it reports which paths
resolved. A source that returns 200 but resolves nothing is
invalid_response, and this is where you find that out.
3. Enable it — Owners only
Enabling is a separate act, and only an Owner can do it.
That asymmetry is deliberate, and it isn't bureaucracy. An Admin can configure a source that points at any URL on the internet, carrying any custom headers, and agents can't see either of those things. Making enablement a second decision, by a higher role, means that pointing Assistive at a new external system is a choice someone with the authority to make it has actually looked at.
Configure and switch on are two questions — does this work? and should we be doing this? — and they belong to different people.
4. Rotate the secret when you need to
Owners and Admins. Rotation is immediate: the old secret stops verifying at once.
Deploy the new secret to your server at the same moment. See the callout on rotation.
5. Agents run lookups
Any member, from a ticket. The agent picks the source, types the parameters, and sees the mapped fields.
Lookups are rate limited.