Skip to main content
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.
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

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us