Platform Configs

Endpoints for creating and managing GitLab and GitHub platform connections used by AI Review.

Platform configs store the credentials and settings required to connect to a GitLab or GitHub instance. All endpoints are under /api/platform-configs and require authentication.

Sensitive fields (accessToken, webhookSecret) are masked in all responses. The raw access token is only available via the admin-only GET /api/platform-configs/:id/access-token endpoint.

---

Platform config schema

The following fields are shared by the create and update endpoints:

name · string · required

Human-readable name for this platform connection (e.g., Company GitLab, GitHub Main).

platformType · string · required

Platform type: gitlab | github.

baseUrl · string · required

Base URL of the platform instance (e.g., https://gitlab.example.com or https://github.com).

authType · string

Authentication mechanism: token (default) | oauth.

accessToken · string

Personal access token (for authType: token) or OAuth2 access token. Required when authType is token.

appId · string

OAuth2 Application ID. Required for authType: oauth.

appSecret · string

OAuth2 Application Secret. Required for authType: oauth.

webhookSecret · string

Secret token used to validate incoming webhook requests.

enabled · boolean

Whether this platform config is active. Default: true.

isDefault · boolean

Mark this as the default platform config. Default: false.

---

List all platform configs

GET /api/platform-configs

Returns all platform configs with secrets masked.

curl -X GET https://your-domain.com/api/platform-configs \
  -H "Authorization: Bearer <api-key>"

Response 200

data.items · array

List of platform config objects. accessToken and webhookSecret are replaced with ***.

---

List enabled platform configs

GET /api/platform-configs/enabled

Returns only platform configs with enabled: true.

---

List platform configs by type

GET /api/platform-configs/type/:platformType

platformType · string · required

gitlab | github

Response 200

data.configs · array

Platform configs of the specified type.

---

Get default platform config

GET /api/platform-configs/default

Returns the platform config marked as isDefault: true, or null if none is set.

Response 200

data.config · object | null

The default platform config, or null.

---

Get a platform config

GET /api/platform-configs/:id

id · string · required

UUID of the platform config.

Response 200

data.config · object

Platform config with secrets masked.

---

Get decrypted access token

GET /api/platform-configs/:id/access-token

Returns the decrypted access token. Requires the admin role.

id · string · required

UUID of the platform config.

Response 200

data.accessToken · string

The raw, decrypted access token.

---

Create a platform config

POST /api/platform-configs

Creates a new platform connection. Requires config:create permission.

For GitLab with authType: token, the server validates that the access token has the required api scope before saving.

curl -X POST https://your-domain.com/api/platform-configs \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company GitLab",
    "platformType": "gitlab",
    "baseUrl": "https://gitlab.example.com",
    "authType": "token",
    "accessToken": "glpat-xxxx",
    "webhookSecret": "my-secret",
    "enabled": true,
    "isDefault": true
  }'

Response 200

data.config · object

The newly created platform config with secrets masked.

---

Update a platform config

PATCH /api/platform-configs/:id

Partially updates an existing platform config. Requires config:update permission.

id · string · required

UUID of the platform config to update.

The request body accepts any subset of the platform config schema fields.

Response 200

data.config · object

Updated platform config with secrets masked.

---

Set as default

POST /api/platform-configs/:id/default

Marks the specified platform config as the default. Requires config:update permission.

id · string · required

UUID of the platform config to promote.

Response 200

data.config · object

Updated platform config.

---

Delete a platform config

DELETE /api/platform-configs/:id

Deletes a platform config. Requires config:delete permission.

If associated projects exist, the request fails with 400 unless the force=true query parameter is provided, which deletes the config and all its associated projects.

id · string · required

UUID of the platform config to delete.

force · string

Pass true to also delete all projects linked to this config.

Response 200

data.success · boolean

true on successful deletion.

data.deletedProjects · number

Number of associated projects deleted (non-zero only when force=true).

---

Test a connection

POST /api/platform-configs/test-connection

Tests whether the provided credentials can successfully connect to the platform. Requires config:update permission.

Request body

platformType · string · required

gitlab | github

baseUrl · string · required

Platform base URL.

accessToken · string

Access token to test.

authType · string

token | oauth. Default: token.

Response 200

data.success · boolean

true if the connection succeeded and at least one project was found.

data.message · string

Human-readable result description.

data.details · object

Additional details such as whether any projects were returned.

---

GitLab user search

GET /api/platform-configs/:id/gitlab/users

Searches GitLab users using the credentials of the specified platform config. Useful for populating reviewer pickers.

id · string · required

UUID of a GitLab platform config.

search · string

Search term.

projectId · string

Limit results to members of a specific platform project.

page · number

Page number. Default: 1.

perPage · number

Items per page. Default: 20, max: 100.

Response 200

data.users · array

Show User fields

id · string

GitLab user ID.

username · string

GitLab username.

name · string

Display name.

avatarUrl · string

Avatar URL.

state · string

Account state.

webUrl · string

Profile URL.

---

GitLab OAuth2 flow

For authType: oauth, use the following endpoints to complete the OAuth2 authorization code flow.

Get the GitLab authorization URL

POST /api/platform-configs/oauth/gitlab/auth-url

Generates the GitLab OAuth2 authorization URL to redirect the user to.

platformConfigId · string · required

UUID of the platform config with authType: oauth.

redirectUri · string · required

The callback URL registered in your GitLab application.

Exchange the authorization code

POST /api/platform-configs/oauth/gitlab/callback

Exchanges the authorization code from GitLab for an access token and stores it.

platformConfigId · string · required

UUID of the platform config.

code · string · required

Authorization code from GitLab.

redirectUri · string · required

Must match the redirectUri used in the authorization step.

Refresh the access token

POST /api/platform-configs/oauth/gitlab/refresh

Uses the stored refresh token to obtain a new access token.

platformConfigId · string · required

UUID of the platform config to refresh.