Integrations and API
Cortex exposes three programmatic surfaces: a REST API documented by each installation's built-in API reference, MCP endpoints for agents and headless clients (Streamable HTTP behind OAuth 2.1 or a minted access token), and the engine call an application uses for its data. Around them sit single sign-on, meeting and Slack intake for the Feed, alerting to Slack, a private git repository per project, and the mail and calendar connectors workflow actors use.
REST API
Every installation serves an interactive API reference listing every operation with its parameters and a try-it-out mode. It is the authoritative description for the version you run.
A sign-in call with email and password returns an access token and the signed-in person; every later call carries the token as a bearer. Where the installation runs a separate accounts service, sign-in and refresh are proxied to it. Single sign-on issues the same kind of session.
Every request is scoped by headers the product's own user interface adds and a client must add too:
| Header | Meaning |
|---|---|
| the project | The project slug; the page address is the source of truth for the active project, never a token claim |
| the branch | The branch of the project's versioned configuration, the main branch by default |
| the organisation | The organisation acted for, when a person belongs to several |
The operation families mirror the product: data sources, targets, nodes and links (Data governance and pipelines); applications and requests (Apps and the Board); requirement sources, requirements, tasks, tests and guides (Requirements and knowledge, Tests and health); the workflow engine (Business workflows); models (Models); deployments and delivery (Deployments and environments).
MCP endpoints
The assistant serves the cortex tools over MCP with the Streamable HTTP transport: a session id is returned on initialise and sent back on every later request. Each project's Settings page shows its endpoint addresses. The endpoint kinds (read-write and read-only per project and branch, the orchestrator with one delegation tool per agent, and the internal loopback surfaces) are listed on Agents and MCP.
OAuth 2.1 discovery follows the standard authorisation-server metadata: issuer, authorisation, token and dynamic client registration endpoints, the authorisation-code and refresh-token grants, and PKCE. Every MCP endpoint publishes protected-resource metadata whose resource is exactly the address the client connected to, so strict clients behind a reverse proxy do not reject on a mismatch. Consent is the cortex sign-in page; every request re-derives access from the bearer's owner. Bearers do not expire and are revoked by deletion.
Access tokens for headless clients
A client without a browser cannot complete consent. Settings, Access tokens for external MCP clients mints the same kind of bearer with a label. The token is shown once and the list carries only its short prefix. The platform signs a short-lived, purpose-bound token and asks the assistant to issue, list or revoke the bearer on the person's behalf. A bearer grants nothing beyond what the person holds, and a read-only endpoint keeps a client from writing the configuration.
An MCP client is pointed at the endpoint address from Settings with the bearer in its authorisation header. The first call initialises a session, the second lists the tools.
The app SDK
An app service that wants the cortex companions includes the SDK with one script tag from its own origin. The application's server proxies the platform API, and the platform serves the script with the cortex address stamped in from the installation's environment settings, so one page works in every environment. The script renders the speed dial with the companions the owner ticked in Viewer options, the chat from the cortex origin and the other companions as chromeless cortex pages, and exposes a small object for refreshing, opening and closing the dial and passing a token. The server's companion list is the only rule. See Applications.
The data call and the identity rule
Every application reads and writes its data through one call naming a project endpoint and an input. The platform resolves the project from the scope header, invokes the endpoint on the engine fork and merges the caller's identity claims (id, email, name) over the input together with the compiled data-access constraints, so an endpoint can trust the identity in its input.
An application must therefore never forward its own identity fields through this call, because the caller's claims overwrite them. An application whose endpoints act on a module's own identity routes such calls through one gateway endpoint on the fork that receives the arguments intact and verifies the identity in its own payload. A person an application is shared with may make this call for that application only.
Working with your existing authorisation
The first question is what is being integrated. A user reaches the project's data through one of two doors, and they differ in who sits in the data path.
Through the application built for you: the application is an app service, your own runtime with your own login and your own authorisation stack, unchanged. Cortex frames it and never sits between it and your data. When that application calls a project endpoint, it can pass whatever your systems require (the user's token, a session handle) in its own arguments, and the endpoint forwards it.
Through cortex itself (the chat, an agent on a workflow step, a companion): the only thing cortex contributes is who is calling. The endpoint receives the caller's identity, verified before it runs, and the signed subject: email, organisation, role, membership attributes, and what your entitlement API answered for that person. Cortex does not reimplement your rules and does not need to see them.
In both cases an endpoint that calls an external system carries that system's own authorisation protocol as its configuration: a client credential, an API key, an OAuth flow, a database role, whatever the system requires. The credentials live in the project's environment settings, never in generated code, a specification or a test. Your integration guide for your access control is a requirement source like any other document, so the fleet builds the connector against it and the requirement stays traceable to it (Requirements and knowledge).
| Situation | How authorisation is inherited |
|---|---|
| The application runs as an app service | Your runtime, your authentication and authorisation, unchanged. An identity provider can itself be one of the project's app services |
| An endpoint calls a customer system (an API, a database with its own rules, stored procedures) | The endpoint forwards the call under the credential you issue for the integration, carrying the verified caller identity and signed attributes. Your layers keep enforcing their rules; the generated endpoint adds none of its own |
| An endpoint reads a governed copy of the data inside cortex | Row filters and column masks compile the same subject into every query. The attributes come from the membership or from your entitlement API through the attribute provider, so tenant isolation follows your own entitlements (Data governance and pipelines) |
Token validation happens before any of this. A session token is signed by the account service and verified against its public keys on every request; an MCP bearer is looked up on every request and revocable at once; a fleet job acting for a person carries a token that can only narrow that person's access. Inside the platform, the hop from the API to the engine carries an internal secret, and the grant that reaches the engine is signed with a per-project secret and expires in five minutes. What is not yet in place on this surface is listed under Security and operations.
Single sign-on
Single sign-on is OpenID Connect against the organisation's workspace identity provider, enabled per installation by the operator. The sign-in page starts the authorisation-code flow; the callback verifies the identity token (issuer discovery, signing keys, nonce), requires a verified email, optionally pins the allowed workspace domain and turns the identity into a cortex session. Multi-factor authentication is enforced at the identity provider. Password sign-in remains for break-glass access and local development.
Meeting intake
The Feed collects call transcripts, summarises them and routes a topic into a project's Requirement sources or Knowledge pages. Connectors are personal (Feed, Settings, Meeting services), and every import is private to its owner until shared.
| Connector | Mode |
|---|---|
| Upload | An audio or video file goes to object storage and is transcribed by the platform's transcription service |
| A pull-based transcript service | The person saves a personal API key; the platform polls hourly, on save and on "Sync now"; an optional webhook only hastens the next poll |
| A push-based meeting-notes service | The person pastes a per-user webhook address into the service; the secret in the address is the authentication, and each finished meeting is pushed as it ends. The same service can also be read by API key, with a first sync reaching back ninety days |
Both modes of a service write the same rows, deduplicated on the meeting's identifier.
Slack
For Feed collection, channels are opted in per organisation and read on an hourly job with a workspace token held by the operator or a personal token saved in Feed settings. Digests become topics routable into Requirement sources or Knowledge. For alerts, a project's health transition posts to an incoming webhook of the installation's alerts channel, prefixed with the environment's name. See Tests and health.
A git repository per project
When git hosting is configured for the installation (a workspace and a credential, with an optional project key and repository prefix), every new project's engine fork gets a private repository at creation and the exporter pushes every export commit to it. Without it, forks keep a local export repository only. The repository is the history a customer keeps; see Independent applications.
Mail and calendar for workflow actors
An email trigger is a listener whose settings hold a mail search query and a processed label. The workflow-actors worker polls it through a mail connector, ingests each new message as a deduplicated event and labels the thread. An actor's manifest declares whether it may use a connector (mail or calendar) or is judgment-only; connector work runs in an interactive worker session, never headless. See Business workflows.
Environment settings
The operator decides per installation which integrations are on: the session signing secret, the cortex address stamped into the app SDK, the single sign-on client and its allowed domain, the transcription service, the Slack workspace token and alerts webhook, and the git hosting workspace and credential. Each is an environment setting of the platform's services, never a value in a project's configuration, so a project moved between environments picks up the destination's integrations.