/mcp on a user’s behalf). An API client is created by a workspace
admin, scoped to that one workspace, and acts as itself.
- Create an API client and choose its scopes.
- Get a token with a client secret or, preferably, a private-key JWT.
- 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, forprivate_key_jwtauthentication. The private key never leaves your side. See Private-key JWT authentication for how to generate 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.
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 policies attached to the group and the
workspace-wide policies that also apply. allowedEntries is their combined connector and tool grant—the
access a hypothetical person in the group 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 returningnot_found means the delete already succeeded —
treat it as success.
