---
title: "Connect BYOA Agent"
method: POST
path: "/agents/connect"
tags: ["Agents"]
---

# Connect BYOA Agent

`POST /agents/connect`

## Request

- Base URL: `https://synchronex.ai/api/v1`
- URL: `https://synchronex.ai/api/v1/agents/connect`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://synchronex.ai/oauth/authorize`, token URL `https://synchronex.ai/api/oauth/token`, scopes: `read`)

Registers a bring-your-own-agent RSA public key (RS256, 2048 bits or larger) and mints a delegated grant. dryRun returns the planned registration without writing. Non-RSA keys are rejected.

## Request body

- ConnectByoaAgentRequest
  - `workspaceId` string, uuid, nullable
  - `name` string, required
  - `publicKey` string, required: SPKI PEM of an RSA public key for RS256 proof-of-possession. Must be 2048 bits or larger. EC and other key types are rejected.
  - `agentScopes` string[], required
  - `proofKeyThumbprint` string, required
  - `expiresAt` string, date-time, required
  - `tokenTtlSeconds` integer
  - `maxSpendUsd` number, nullable
  - `dryRun` boolean
  - `metadata` object
    - `agentScopes` string[]
    - `label` string, nullable
    - `provider` string, nullable
    - `homepageUrl` string, uri, nullable
    - `contactEmail` string, email, nullable
    - `safetyMode` 'read_only' | 'approval_first'
    - `allowHumanOnlyTools` false

## Response `200`

Dry-run connection plan.

- object
  - `connected` false, required
  - `dryRun` true, required
  - `registration` object, required
    - `workspaceId` string, uuid, nullable
    - `name` string
    - `declaredCapabilities` object
    - `metadata` object
  - `grant` object, required
    - `scope` 'read' | 'write'
    - `allowedTools` string[]
    - `maxSpendUsd` number, nullable
    - `expiresAt` string, date-time
    - `remainingDepth` integer
    - `metadata` object
  - `safety` ConnectedAgentSafety, required
    - `rawDatabaseAccess` false, required
    - `fullIdentityKernelDump` false, required
    - `highRiskAutonomousExecution` false, required
    - `circuitBreakers` object, required
      - `burst` object, required
        - `limit` integer, required
        - `windowSeconds` integer, required
      - `writeLoop` object, required
        - `limit` integer, required
        - `windowSeconds` integer, required

## Other responses

- `201`: Agent connected and grant minted.
- `400`: Validation error. The request body or query string is invalid.
- `401`: Unauthorized. Missing, malformed, expired, or revoked bearer token.
- `403`: Forbidden. The token scope or account tier is insufficient.
- `429`: Rate limit exceeded. Retry after the indicated reset time.

---

[API](https://skmtc.dev/synchronex/apis/synchronex-api.md) · [All operations](https://skmtc.dev/synchronex/apis/synchronex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/synchronex/apis/synchronex-api/revisions/aa1e0df0a8d5?raw)