> ## Documentation Index
> Fetch the complete documentation index at: https://pipedream.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> Call Conduit's workspace-admin operations from scripts and CI using machine-to-machine OAuth, with no user in the flow.

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](#create-an-api-client) and choose its
   [scopes](/docs/conduit/use/api/scopes).
2. [Get a token](/docs/conduit/use/api/authentication) with a client secret or,
   preferably, a private-key JWT.
3. [Call the API](#call-the-api) with the token.

## Create an API client

In **Settings → API Clients**, create a client and choose its
[scopes](/docs/conduit/use/api/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](/docs/conduit/use/api/authentication#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.

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"organizationId\": \"$ORG\"}" \
  https://conduit.example.com/conduit.v1.ConduitService/ListConnectors
```

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](/docs/conduit/use/api-reference/connectors/list-connectors)** 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](/docs/conduit/use/api/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.