# Finalize a GitLab connection via the OAuth callback

Source: https://docs.levelfour.ai/api-reference/accounts/post-accounts-integrations-by-id-gitlab-complete


## POST /api/v1/accounts/integrations/{integration_id}/gitlab-complete

### Authentication

Send `Authorization: Bearer <token>`.

### Parameters

- `integration_id` (path, string, required)

### Request body

Required. Content type `application/json`.

- `code` (string, required): OAuth authorization code returned to the GitLab callback
- `namespace` (string, nullable): Legacy single-target path. When scope='group', a group full path (e.g. acme or acme/infra). When scope='project', a single project full path (e.g. acme/infra/billing). Provide either namespace (legacy) or projects (multi-project mint-and-store), not both.
- `projects` (array of string, nullable): Multi-project path: one or more project full paths (e.g. acme/infra/billing). Requires scope='project'. Each project mints its own scoped Project Access Token at connect time so the bot has a per-project identity and the connector's OAuth token is never stored.
- `scope` (one of `group`, `project`, default `group`): Whether to connect an entire group (registers a group webhook, needs GitLab Premium/Ultimate) or one or more projects (registers a project webhook each, works on all tiers).
- `gitlab_host` (string, nullable): Base URL of the GitLab instance for self-managed customers. Defaults to gitlab.com.

### Responses

#### 200: Multi-project connect result (when projects is supplied). Partial success is a 200: see connected_count / failed_count and per-project results.

- `success` (boolean, default `true`)
- `timestamp` (date-time string)
- `data` (object, required)
  - `integration_id` (string, required): The integration this multi-project connect finalized
  - `results` (array of object, required): One result per requested project, in request order
    - `project_path` (string, required): The project full path this result is for
    - `status` (one of `connected`, `needs_permission`, `tier_unsupported`, `not_found`, `error`, required): Per-project outcome. connected: PAT minted and stored. needs_permission: the connector's GitLab role cannot mint a Project Access Token. tier_unsupported: the GitLab plan does not offer Project Access Tokens. not_found: the project path did not resolve. error: an unexpected failure for this project only.
    - `connection_id` (string, nullable): Stored connection id when status='connected'
    - `bot_user_id` (integer, nullable): The Project Access Token bot user id when status='connected'
    - `webhook_id` (integer, nullable): The registered project webhook id when status='connected'
    - `message` (string, nullable): Human-readable detail for a non-connected status
  - `connected_count` (integer, required): Number of projects that connected successfully
  - `failed_count` (integer, required): Number of projects that did not connect

#### 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)