GET /organizations/:organization_name/oauth-clients
Parameter
Description
:organization_name
The name of the organization.
This endpoint allows you to list VCS connections between an organization and a VCS provider (GitHub, Bitbucket, or GitLab) for use when creating or setting up workspaces.
This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results.
Parameter
Description
page[number]
Optional. If omitted, the endpoint will return the first page.
page[size]
Optional. If omitted, the endpoint will return 20 oauth clients per page.
POST /organizations/:organization_name/oauth-clients
Parameter
Description
:organization_name
The name of the organization that will be connected to the VCS provider. The organization must already exist in the system, and the user must have permission to manage VCS settings. (More about permissions.)
This endpoint allows you to create a VCS connection between an organization and a VCS provider (GitHub or GitLab) for use when creating or setting up workspaces. By using this API endpoint, you can provide a pre-generated OAuth token string instead of going through the process of creating a GitHub or GitLab OAuth Application.
To learn how to generate one of these token strings for your VCS provider, you can read the following documentation:
This POST endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path
Type
Default
Description
data.type
string
Must be "oauth-clients".
data.attributes.service-provider
string
The VCS provider being connected with. Valid options are "github", "github_enterprise", "gitlab_hosted", "gitlab_community_edition", "gitlab_enterprise_edition", or "ado_server".
data.attributes.name
string
null
An optional display name for the OAuth Client. If left null, the UI will default to the display name of the VCS provider.
data.attributes.key
string
The OAuth Client key. It can refer to a Consumer Key, Application Key, or another type of client key for the VCS provider.
data.attributes.http-url
string
The homepage of your VCS provider (e.g. "https://github.com" or "https://ghe.example.com")
data.attributes.api-url
string
The base URL of your VCS provider's API (e.g. "https://api.github.com" or "https://ghe.example.com/api/v3")
data.attributes.oauth-token-string
string
The token string you were given by your VCS provider
data.attributes.private-key
string
Required for Azure DevOps Server. Not used for any other providers. The text of the SSH private key associated with your Azure DevOps Server account.
data.attributes.secret
string
The OAuth Client secret. For BitBucket Server, this secret is the the text of the SSH private key associated with your BitBucket Server Application Link.
data.attributes.rsa-public-key
string
Required for BitBucket Server in conjunction with the secret. Not used for any other providers. The text of the SSH public key associated with your BitBucket Server Application Link.
This PATCH endpoint requires a JSON object with the following properties as a request payload.
Key path
Type
Default
Description
data.type
string
Must be "oauth-clients".
data.attributes.name
string
(previous value)
An optional display name for the OAuth Client. If set to null, the UI will default to the display name of the VCS provider.
data.attributes.key
string
(previous value)
The OAuth Client key. It can refer to a Consumer Key, Application Key, or another type of client key for the VCS provider.
data.attributes.secret
string
(previous value)
The OAuth Client secret. For BitBucket Server, this secret is the the text of the SSH private key associated with your BitBucket Server Application Link.
data.attributes.rsa-public-key
string
(previous value)
Required for BitBucket Server in conjunction with the secret. Not used for any other providers. The text of the SSH public key associated with your BitBucket Server Application Link.
This endpoint allows you to remove an existing connection between an organization and a VCS provider (GitHub, Bitbucket, or GitLab).
Note: Removing the OAuth Client will unlink workspaces that use this connection from their repositories, and these workspaces will need to be manually linked to another repository.
