---
title: "Start or replay guided cloud setup"
method: POST
path: "/v1/cloud-onboarding-sessions"
tags: ["Cloud observation"]
---

# Start or replay guided cloud setup

`POST /v1/cloud-onboarding-sessions`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/cloud-onboarding-sessions`
- Auth: HTTP bearer

Requires an API key owned by a user who is currently a team administrator. Keys without a user owner do not inherit administrator access. The console uses the same service with its authenticated session. Creates setup intent only. Requires configured guided deployment settings for the selected provider. Same normalized settings and key return the same session without extending expiry. Changed settings or more than five active sessions return 409 cloud_onboarding_conflict. Missing deployment settings return 503 cloud_setup_unavailable. No observation connection is created until verification succeeds.

## Headers

- `Idempotency-Key` string, required

## Request body

- CloudOnboardingInput
  - `provider` 'aws' | 'gcp', required
  - `name` string: Optional name, trimmed on submission. Empty or omitted values become AWS or Google Cloud for the selected provider. At most 100 UTF-8 bytes.
  - `regions` string[], nullable: Commercial AWS regions only. GovCloud and China partitions are not supported by this connection flow. Omitted, null, or empty discovers all enabled account regions. A nonempty list restricts collection. Region order does not affect idempotency. GCP requires an empty list.
  - `project_id` string: Google Cloud project ID. Required for GCP and omitted for AWS.
  - `billing_location` 'US' | 'EU': Location of the dedicated Google Cloud billing dataset. Defaults to US for GCP and is omitted for AWS.

## Response `201`

Start or replay guided cloud setup

- CloudOnboardingResponse: Connection is included after completion while it remains connected. A completed receipt never reconnects a disconnected account.
  - `session` CloudOnboardingSession, required: Setup expires after 24 hours. Expired pending records remain readable with their original expiry and cannot complete. Only unexpired pending records appear in the active list.
    - `id` string, required: Opaque server-generated setup identity.
    - `provider` 'aws' | 'gcp', required
    - `name` string, required
    - `regions` string[], required: AWS enabled account regions when empty. Always an array and empty for Google Cloud.
    - `role_name` string, required: Prepared AWS role name. Empty for Google Cloud.
    - `state` 'pending' | 'completed' | 'cancelled', required
    - `expires_at` string, date-time, required
    - `connection_id` string: Present after completion. A later disconnect does not remove this completion receipt.
    - `revision` integer, required
    - `created_at` string, date-time, required
    - `project_id` string: Google Cloud project ID. Required for GCP and omitted for AWS.
    - `billing_location` 'US' | 'EU': Location of the dedicated Google Cloud billing dataset. Defaults to US for GCP and is omitted for AWS.
    - `project_number` string: Google Cloud project number verified for this connection.
  - `next_action` CloudOnboardingAction, required
    - `type` 'open_provider' | 'unavailable' | 'expired' | 'completed' | 'cancelled', required
    - `url` string, uri: Prepared AWS CloudFormation approval or Google Cloud Shell URL, present for open_provider.
    - `message` string: Explanation when guided setup is unavailable.
    - `setup_command` string: Reviewable Google Cloud Shell setup command. Present only for pending GCP setup. Does not contain credentials.
  - `connection` CloudObservationConnection
    - `id` string, required
    - `provider` 'aws' | 'gcp' | 'azure', required
    - `scope` string, required
    - `config` CloudObservationConfig, required: Account identity and read scope. Fields depend on the provider. Credentials are never returned.
      - `provider` 'aws' | 'gcp' | 'azure', required
      - `name` string, required
      - `role_arn` string
      - `project_id` string
      - `billing_table` string
      - `billing_location` string
      - `billing_scope` string
      - `directory_id` string
      - `subscription_id` string
      - `client_id` string
      - `regions` string[]
    - `state` 'pending' | 'collecting' | 'ready' | 'partial' | 'error', required
    - `last_attempt_at` string, date-time, nullable, required
    - `last_success_at` string, date-time, nullable, required
    - `created_at` string, date-time, required

## Other responses

- `default`: Authentication, administrator access, invalid input, missing records, conflicts, rate limits, credential storage, and transient failures are returned using the stable error and message fields.

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)