# Enroll a Cloud Connect cluster or standalone runtime

`POST /v1/cloud-connect/enroll`

Token enrollment accepts a canonical kind-bound enrollment token. Standalone enrollment may instead use user Authorization plus X-Org-Name. Idempotency-Key is required for standalone enrollment.

## Header parameters

- `Authorization` (string, optional): `Bearer <token>`. [Authentication](https://spice.ai/docs/cloud/api/management#authentication) lists the tokens it accepts.
- `Idempotency-Key` (string (uuid), optional)
- `X-Org-Name` (string, optional): Required with Bearer authorization for authenticated standalone enrollment; omitted for token enrollment.

## Request body

Required.

Content type: `application/json`

One of:

- **kind: standalone, with token** (object)
  - `kind` (string, required): Value: `standalone`.
  - `token` (string, required): Pattern: `^spice-enroll-[A-Za-z0-9_-]{32}$`.
  - `expected_org` (string)
  - `csr_pem` (string, required)
  - `enc_pubkey_pem` (string, required)
  - `instance` (object, required)
  - `region` (string)
- **kind: cluster** (object)
  - `kind` (string, required): Value: `cluster`.
  - `token` (string, required): Pattern: `^spice-enroll-[A-Za-z0-9_-]{32}$`.
  - `expected_org` (string)
  - `csr_pem` (string, required)
  - `enc_pubkey_pem` (string, required)
- **kind: standalone, without token** (object)
  - `kind` (string, required): Value: `standalone`.
  - `csr_pem` (string, required)
  - `enc_pubkey_pem` (string, required)
  - `instance` (object, required)
  - `region` (string)

## Example request

```bash
curl -X POST "https://api.spice.ai/v1/cloud-connect/enroll" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "standalone",
    "token": "string",
    "csr_pem": "string",
    "enc_pubkey_pem": "string",
    "instance": {}
  }'
```

```http
POST /v1/cloud-connect/enroll HTTP/1.1
Host: api.spice.ai
Content-Type: application/json
Content-Length: 118

{
  "kind": "standalone",
  "token": "string",
  "csr_pem": "string",
  "enc_pubkey_pem": "string",
  "instance": {}
}
```

## Responses

**200 OK**

Enrollment completed or exactly replayed

Content type: `application/json`

One of:

- **kind: standalone** (object)
  - `kind` (string, required): Value: `standalone`.
  - `instance_id` (string, required)
  - `identity_cert_pem` (string, required)
  - `ca_bundle_pem` (string, required)
  - `gateway_addr` (string, required)
  - `not_after` (string (date-time), required)
  - `organization` (object, required)
    - `id` (integer, required)
    - `name` (string, required)
  - `region` (string, required)
  - `portal` (object, required)
    - `new_project_url` (string (uri), required)
  - `attachment` (null, required)
  - `recovered` (boolean, required)
- **kind: cluster** (object)
  - `kind` (string, required): Value: `cluster`.
  - `connection_id` (string, required)
  - `identity_cert_pem` (string, required)
  - `ca_bundle_pem` (string, required)
  - `gateway_addr` (string, required)
  - `not_after` (string (date-time), required)
  - `organization` (object, required)
    - `id` (integer, required)
    - `name` (string, required)
  - `region` (string, required)
  - `attachment` (null, required)

**400 Bad Request**

Invalid request, kind mismatch, or unsupported project field

**401 Unauthorized**

Invalid credential or authorization

**403 Forbidden**

Authenticated caller lacks the required scope or organization role

**409 Conflict**

Consumed token, connection already enrolled, unavailable connection, organization mismatch, or idempotency mismatch

**410 Gone**

Enrollment token or authenticated recovery window expired

**413 Content Too Large**

Request body too large

**500 Internal Server Error**

Internal or identity-provider failure; use the retryable response field

OpenAPI: [api.spice.ai/openapi.json](https://api.spice.ai/openapi.json)