Integrations and API keys | Cooriroo Documentation

Integrations is where you mint the credentials that let something other than a browser use your Cooriroo data — a warehouse system, a reporting job, a script, or an AI client. Everything on the page is built around one object: the API key. A key is a credential in its own right, and what it can reach is decided by the scopes you attach to it.

Who can do this

Role: Administrators
Permission: api-keys:write

Keys are personal: you see and manage only the keys you created, never a colleague’s. Creating, rotating and revoking a key always requires a signed-in session — a key can never mint or revoke another key.

What a key can do, and what decides it

A key does not inherit your roles. When a request arrives with a key, the scopes on that key are the whole of its authority: your own permissions are not consulted, and neither is the role of the person who happens to be holding the secret. That is the single most important thing to internalise before you create one — a key with no scopes can reach nothing, and a key with every scope can do everything you could.

A scope is written resource:action — for example trips:read or destinations:write. Actions are read, write and delete. The key stays inside your tenant either way: tenant isolation is enforced beneath the credential, so a key can never see another tenant’s records however it is scoped.

Creating a key

The create flow is three steps, then a one-time reveal of the secret.

1
Identity — name it after the thing that will use it
Integrations → Create API key → Identity
Give the key a name and a description that says which system holds it. Six months from now, the name is the only thing that tells you whether a key is safe to revoke. Set an expiry here as well: 30, 90, 180 or 365 days, or no expiry. Ninety days is the recommended default.
2
Permissions — pick a preset, then trim it
Integrations → Create API key → Permissions
Choose one of the presets as a starting point and remove anything the integration does not need. The catalog offers no global wildcard, so the narrowest working set is always expressible.
3
Restrict and review — network limits and a final check
Integrations → Create API key → Restrict & review
Optionally pin the key to specific IP addresses or CIDR ranges, and set a per-key rate limit in requests per minute. Review the scope list one last time before you create it.
4
Copy the secret
The full secret is displayed once, immediately after creation. Paste it straight into the system that needs it. Afterwards the list shows only the key’s short prefix, which is enough to identify it and useless as a credential.

Scope presets

Preset	What it grants	Use it for
Read-only	Read on every resource in the catalog, nothing else	Reporting, BI extracts, audits
Dispatch	Read and write on trips, tasks, destinations and exceptions	A system that plans or updates work
Maintenance	Read and write on work orders, schedules and inspections	A workshop or servicing system
Full access	Every action on every resource, delete included	Rarely — prefer a trimmed preset

The four presets in the create wizard. Each one is a starting point you can edit.

Narrowing a key further

Scopes decide what a key may do. Three further settings decide when, from where and how fast it may do it:

Expiry — after the date passes, the key reads as Expired and stops working. A key with no expiry never lapses, which is convenient and is exactly why a forgotten one stays useful to whoever finds it.
IP allowlist — plain addresses or CIDR ranges. An empty list allows any address. Entries that are not valid addresses or ranges are ignored rather than treated as wildcards, so a typo narrows access, never widens it.
Rate limit — requests per minute for this key alone. Leave it unset and the key is bounded only by the platform-wide limits.

Rotating, revoking and deleting

	Rotate	Revoke	Delete
What happens	A new secret is issued at once	The key is permanently disabled	The key record is removed
Old secret	Stops working immediately	Stops working immediately	Stops working immediately
Name and scopes	Kept	Kept, shown as Revoked	Gone from the list
Reversible	Yes — rotate again	No	No
Use when	On a schedule, or after a leak	The integration is retired	Tidying up a key never used

Three ways to end a key’s usefulness. Only rotation is meant to be routine.

Rotation is the safe default because it keeps the key’s identity: the same name, the same scopes, the same audit trail, a new secret. Plan for the gap — the old secret stops working the instant the new one is issued, so the receiving system has to be updated straight away rather than at the end of the week.

Connecting an AI client

The same page can point an AI client at your fleet data over the Cooriroo MCP endpoint. It gives you a ready-to-paste configuration — a CLI command and a JSON block — with a placeholder where your key goes. You can narrow the endpoint to one or more areas: Fleet, Dispatch, Workforce, Network or Support. Selecting nothing exposes every tool.

Choosing areas is a context decision, not a permission one. It changes how many tools the client is offered, not what it is allowed to do — the pasted key’s scopes still decide that, exactly as they would for a script. A read-only key handed to an AI client stays read-only. The MCP endpoint is also gated: if it is not part of your plan the card is replaced by a locked placeholder rather than a broken setup flow.

External system integrations

API keys are the outward-facing half of integration: something else calls Cooriroo. The inward half — a scheduled connector that pulls records from an external system into your destinations — works the other way and is set up differently. The whole subsystem sits behind an entitlement, so it is invisible until the platform team enables it for your tenant.

Once it is enabled, an admin can list the configured connectors, inspect the run history, and trigger a sync on demand. Creating, editing or deleting a connector is a platform-team action, because a connector’s configuration names an external host and a stored credential — decisions that belong outside the tenant. Responses only ever show the pointer to a credential, never the credential.