Integrators, security reviewers

Authentication and keys

The request and approval flow, the Authorization and X-API-Key headers, what a key's scope means, revocation, the exact meaning of 401, 403, 404, 422 and 429, and what the access log records.

Last reviewed 1 Nov 2026

Request and approval

Sign in with a work e-mail. The account must not be linked to a farm or co-op profile: those accounts cannot request agency access.
On Request data access name the organisation, the purpose (what the data is for and who will see it), the bays, the products, the aggregation (bay or site) and the date range. At most five requests may wait for review at once.
An administrator approves or declines the request. On approval the account becomes an agency account and the administrator receives the first key, shown once, which they send to you over a secure channel. Only the SHA-256 hash of a key is stored; its first characters (ci_agency_ and six more) are kept to tell keys apart in lists.
An administrator can issue another key for the same request (rotation, a second system) and revoke any one of them.

Sending the key

Send the key with every request, in either header:

Authorization: Bearer <key>
X-API-Key: <key>

The same key works for REST (https://coastal-intelligence.triskelionaisystems.com/api/agency/..., the signed export) and for MCP (https://coastal-intelligence.triskelionaisystems.com/api/mcp). Keep it in an environment variable or a secret store, never in a file you share or commit.

Scope

A key reads exactly its approved request, along four dimensions. A call outside any of them is refused, not narrowed:

Dimension	Rule
Bays	A tool naming another bay, or a site in another bay, is refused.
Products	The derived families (`signals`, `events`, `skill`, `backtest`, `risk_index`) and, for time series, each dataset key. Operator records are never a product.
Aggregation	`bay`: bay aggregates only; a site argument must be a ground-truth station (buoy, tide gauge). `site`: per-site series too.
Date range	Explicit `from` / `to` values must lie inside it. Omitted bounds default to the last 30 days up to today plus the 10-day forecast horizon, clipped to the range. One call covers at most 366 days.

Every result echoes the scope it was answered under (scope: request id, organisation, bays, products, aggregation, from, to), so a client can check what it is reading.

Revocation

An administrator can revoke one key or the whole request at any time; the next call with it is answered 401. A request that is no longer approved (declined, revoked) disables all its keys at once. To change a scope, send a new request; keys are never widened in place.

Status codes

Status	Meaning	Notes
401	No key, an unknown key, a revoked key, or a key whose request is no longer approved.	The answer does not say which. Header `WWW-Authenticate: Bearer realm="coastal-intelligence-agency"`. Over MCP this is an HTTP 401 before the protocol starts.
403	Outside the key's scope: another bay, a product not approved, site data under bay aggregation, a date outside the range.	REST only. Over MCP the same refusal is a tool result with isError true and the reason as text.
404	Unknown bay or site id, unknown tool, or no back-test exists for the bay.	Over MCP: a tool error.
422	A bad parameter: an unknown signal kind or variable, from after to, a window above the maximum, or a result above the row limit.	Narrow `from` / `to` or the filters. Over MCP: a tool error; an argument the tool does not declare is refused too.
429	More than the rate limit (60 calls per minute per key by default), REST and MCP together.	Header `Retry-After` gives the seconds to wait.

REST error bodies are {"detail": "..."}. The MCP tool-error shape is on the MCP server page.

What the log records

Every call writes one access-log row, refused calls included:

time, key id and key prefix, access request id, account id;
channel (rest or mcp), tool, the tool's own arguments (bay, site, product, dates);
outcome (ok, denied, not_found, invalid, error, unauthorized, rate_limited), status code, row count, a short detail for refusals;
the client IP, truncated.

The key itself is never logged: only its id and prefix. Requests, approvals, denials, revocations and key issues are recorded in the administrators' audit log too. Administrators read the access log in the app.

Integrators, data engineers

REST API

The base URL of this deployment, every partner endpoint with its parameters, the date rules, the response envelope field by field, examples in curl, Python and JavaScript, and the live OpenAPI reference.

Last reviewed 1 Nov 2026 Analysts with an AI assistant, agent builders

MCP server

The Model Context Protocol server for AI assistants and agents: endpoint and transport, the auth header, every tool with its typed arguments, the tool-error shape, client configurations, the configuration checker and example prompts.