Skip to main content
The API lets scripts, CI jobs, and background services run a workspace’s admin operations — managing connectors, policies, groups, and reading the audit log — with no signed-in user. It is the same Connect RPC API the web UI uses, authenticated by a workspace API client (a machine principal) via OAuth 2.0 client credentials. API clients are distinct from MCP Clients (the interactive OAuth apps that connect to /mcp on a user’s behalf). An API client is created by a workspace admin, scoped to that one workspace, and acts as itself.
  1. Create an API client and choose its scopes.
  2. Get a token with a client secret or, preferably, a private-key JWT.
  3. Call the API with the token.

​
Create an API client

In Settings → API Clients, create a client and choose its scopes; its credentials dialog opens next, to add a credential. Both are edited later from the client’s row menu (Edit scopes, Manage credentials). A credential is either:
  • Client secret — shown once at creation; store it in a secrets manager.
  • Public key — paste an RSA (≥ 2048-bit) or EC P-256 public key, as a PEM (-----BEGIN PUBLIC KEY-----) or a JWK, for private_key_jwt authentication. The private key never leaves your side. See Private-key JWT authentication for how to generate one.
A client can hold several credentials at once, so you rotate make-before-break: add the new one, deploy it, then revoke the old one.

​
Call the API

Every operation is a Connect RPC: POST to https://conduit.example.com/conduit.v1.ConduitService/<Method> with a JSON body and a bearer token. Every workspace method takes organizationId, the workspace the call acts on. An API client belongs to one workspace, so the field is optional: omit it and the call acts on that workspace. Naming any other workspace is refused.
Connector list responses include each connector’s canonical id. Pass that value unchanged to GetConnector to retrieve one connector’s configuration; pass it to ListConnectorCatalogTools for the connector’s full tool metadata and a resolution status. All three operations require connectors:read. To inspect the access granted through one group, call GetGroupAccess with its groupId. The response identifies the group’s transitive parent groups, the policies attached through that hierarchy, and the workspace-wide policies that also apply. allowedEntries is their combined connector and tool grant—the access a hypothetical member would receive if they enabled every allowed tool. It deliberately excludes grants attached directly to individual users and each user’s personal enable selection. This operation requires policies:read. Read-only methods are also servable over GET. Errors use the Connect envelope: a stable machine-readable code (invalid_argument, not_found, permission_denied, failed_precondition, already_exists, resource_exhausted, …), a human message, and the matching HTTP status. Parse the code, never the message. The API reference lists every method, its request and response fields, and an example — generated from the API definition, so it’s always current. It covers exactly the methods reachable with an API client (see Scopes).

​
Retries

Reads and updates are safe to retry. A retried create may duplicate, so make creates idempotent in your own tooling (or check for the resource first). A retried delete returning not_found means the delete already succeeded — treat it as success.