Connect another app to Cardinal
A key lets another app read your workspace without a person signing in. This page is for the workspace owner; nobody else sees it.
What a key does
- It reads this workspace with the owner's view. It never changes anything.
- One key works for both the MCP server (for AI assistants) and the REST API (for data pipelines and Power BI).
- It does not share private briefings and questions, personal assistant data, sign-in details or connection secrets.
Make a key
- Open Settings › API keys.
- Under New key, give the key a label (where it will be used, for example Power BI), choose when it expires and, if you want, Limit to one client.
- Press Create key and copy the key at once: it is shown only once.
You can revoke a key at any time; apps using it stop at once. A workspace can have at most 10 live keys. Only the workspace owner can make or revoke keys.
Keep a key safe
- Make one labelled key per app, so each can be revoked alone.
- Prefer a key limited to one client, with an expiry.
- Anyone who can edit a Power BI report or a flow can read the key inside it. Share those with care.
Which apps can connect
Anything that can send an Authorization header. A hosted assistant that only offers OAuth can't connect yet.
Copilot Studio and Power Automate: choose API key authentication, header Authorization, value Bearer cak_….
For an AI assistant
The MCP address is:
https://cardinal.ramcore.io/api/connect/mcp
For any MCP client, add a server like this:
{
"mcpServers": {
"cardinal": {
"type": "http",
"url": "https://cardinal.ramcore.io/api/connect/mcp",
"headers": { "Authorization": "Bearer ${CARDINAL_KEY}" }
}
}
}Set CARDINAL_KEY in the environment rather than pasting the key into the file.
In Claude Code, one line does it:
claude mcp add --transport http cardinal https://cardinal.ramcore.io/api/connect/mcp --header "Authorization: Bearer cak_…"
For a pipeline
The base address is https://cardinal.ramcore.io/api/connect/v1. The resources are workspace, clients, projects, time-entries, sessions, daily-hours, members, invoices, quotes, deals and figures. The API description is the base address plus /openapi.json.
- Lists answer
{ "data": [...], "nextCursor": ... }. PassnextCursorback ascursorfor the next page; it is null on the last page.limitsets the page size. - Dates are local days (
2026-09-30) in the workspace's time zone. Moments are ISO 8601 in UTC, ending inZ. - Money is whole cents with a
currencyfield. - Time entries and sessions come in windows of up to 92 days (
fromandto, both included). Each row belongs to the window it starts in, so windows can be appended without duplicates.
curl -H "Authorization: Bearer cak_…" https://cardinal.ramcore.io/api/connect/v1/workspace curl -H "Authorization: Bearer cak_…" "https://cardinal.ramcore.io/api/connect/v1/clients?limit=100"
Power BI
- Get data › Web, then Advanced.
- URL:
https://cardinal.ramcore.io/api/connect/v1/clients. - HTTP request header parameters:
Authorizationwith the valueBearer cak_….
To page through every client in Power Query, use a blank query:
let
Page = (cursor as nullable text) =>
Json.Document(Web.Contents("https://cardinal.ramcore.io/api/connect/v1", [
RelativePath = "clients",
Query = if cursor = null then [limit = "200"] else [limit = "200", cursor = cursor],
Headers = [Authorization = "Bearer cak_…"]
])),
Pages = List.Generate(
() => Page(null),
each _ <> null,
each if [nextCursor] = null then null else Page([nextCursor]),
each [data]
),
Result = Table.FromRecords(List.Combine(Pages))
in
ResultFor time entries, walk 92-day windows and page inside each:
let
Headers = [Authorization = "Bearer cak_…"],
Page = (query as record) =>
Json.Document(Web.Contents("https://cardinal.ramcore.io/api/connect/v1", [RelativePath = "time-entries", Query = query, Headers = Headers])),
Window = (from as date, to as date) =>
let
First = [from = Date.ToText(from, "yyyy-MM-dd"), to = Date.ToText(to, "yyyy-MM-dd"), limit = "200"],
Pages = List.Generate(
() => Page(First),
each _ <> null,
each if [nextCursor] = null then null else Page(First & [cursor = [nextCursor]]),
each [data]
)
in
List.Combine(Pages),
Start = #date(2026, 1, 1),
Today = Date.From(DateTime.LocalNow()),
Count = Number.RoundUp((Duration.Days(Today - Start) + 1) / 92),
Rows = List.Combine(List.Transform(List.Numbers(0, Count), each
Window(Date.AddDays(Start, _ * 92), List.Min({Date.AddDays(Start, _ * 92 + 91), Today})))),
Result = Table.FromRecords(Rows)
in
ResultFor a scheduled refresh in the Power BI service:
- Choose Anonymous credentials. The header is already in the query.
- Tick "Skip test connection".
- Set a privacy level (Organizational).
Limit a key to one client
A key made with Limit to one client reads only that client:
- the client and its contacts, its projects, the time, daily hours and Claude sessions on them;
- its invoices and credit notes once issued, and its quotes once sent (sent, accepted or declined);
- members' names.
It never shows: drafts of any kind, deals, other clients, totals across clients, your costs, cost rates, rate card, margins, the ledger or anyone's email. A quote's invoiced amount counts issued invoices only.
A project that has since moved to another client shows as empty, also on an invoice line. Over MCP such a key offers only the invoice list, one invoice and the quote list. Asking for another client is refused, and asking for deals answers 404.
Archiving the client doesn't stop the key. Revoke it.
What your workspace includes
- Invoices and quotes: only where the workspace keeps its books in Cardinal.
- Projects, time entries and sessions: only with the Cardinal tracker.
- Deals: on Premium.
- Claude hours: everyone's on Premium, otherwise yours.
Anything else answers 403 with the reason.
Limits and errors
- 120 requests a minute per key. Over that you get 429; wait the seconds in the
Retry-Afterheader. - 401: the key is unknown, revoked or expired.
- 402: the workspace is paused.
- 403: the workspace doesn't include that resource.
- 410: the workspace has ended. Download the export from Settings instead.
Keys revoked when a workspace's access ended for good stay revoked after it is restored. Make new ones.
Connect the Satchel
An AI assistant or a data pipeline in a client's operating system, like the Satchel, connects the same way. The normal case: the agency's owner, on the agency's own Cardinal workspace, makes a key with Limit to one client set to that client, and gives it to the client.
- The client's assistant uses the MCP address.
- The client's pipeline uses the REST address and the API description.
- Make one key per use, one for the assistant and one for the pipeline, each labelled, so each can be revoked alone.