# Start a connect-accounts integration session

Source: https://docs.levelfour.ai/api-reference/accounts/post-accounts-integrations


## POST /api/v1/accounts/integrations

### Authentication

Send `Authorization: Bearer <token>`.

### Request body

Required. Content type `application/json`.

- `provider` (one of `aws`, `gcp`, `github`, `gitlab`, `jira`, `slack`, default `aws`): Cloud provider identifier
- `mode` (one of `single`, `organization`, `github_app`, `gitlab_oauth`, `jira_oauth`, `slack_oauth`, required): Onboarding mode. AWS: single|organization. GitHub: github_app. GitLab: gitlab_oauth. Jira: jira_oauth. Slack: slack_oauth.
- `target_ou_id` (string, nullable): AWS Organizations root ID (r-...) or organizational unit ID (ou-...-...). Required when provider='aws' and mode='organization'; ignored otherwise.
- `gitlab_host` (string, nullable): Base URL of the GitLab instance for self-managed customers, e.g. https://gitlab.acme.com. Optional when provider='gitlab' (defaults to gitlab.com); ignored otherwise.

### Responses

#### 201: Successful Response

- `success` (boolean, default `true`)
- `timestamp` (date-time string)
- `data` (object, required)
  - `integration_id` (string, required): UUID minted per click; correlates pingback/callback to dashboard session
  - `launch_stack_url` (string, nullable): AWS Console quickcreate URL with pre-filled CFN parameters. Populated when provider='aws'.
  - `launch_install_url` (string, nullable): Provider authorization URL with state parameter. GitHub: App install URL. GitLab: OAuth authorize URL. Jira: Atlassian OAuth 2.0 (3LO) authorize URL. Populated when provider is github, gitlab, or jira.
  - `connect_command` (string, nullable): Shell command the customer pastes into their own Cloud Shell to grant LevelFour read access. Populated when provider='gcp'.
  - `expires_at` (date-time string, required): When the integration session expires (no pingback/callback received)

#### Errors

- `400`: Bad Request
- `401`: Authentication Error
- `403`: Authorization Error
- `404`: Not Found
- `409`: Conflict
- `422`: Validation Error
- `429`: Rate Limit Exceeded
- `500`: Internal Server Error

Body of `400`, `401`, `403`, `404`, `409`, `422`, `429`, `500`:

- `success` (`false`, required)
- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `details` (any)
- `timestamp` (date-time string, required)