Skip to main content
Version: 13.x (Current)

Provider APIs Reference

We report in this section the APIs used to create and modify providers, along with examples of request bodies:

  • POST - /api/backend/tenants/{tenantId}/providers: used to create a new provider;
  • PATCH - /api/backend/tenants/{tenantId}/providers/{providerId}: used to edit an existing provider.
info

These APIs are protected and can be used only if you belong to the group access_token_manager.

POST

To create a new provider, you need to call the respective API as follows:

curl --location --request POST 'https://console-url/api/backend/tenants/my-example-company/providers' \
--header 'Cookie: sid={{CHANGE_ME_WITH_YOUR_SID}}' \
--header 'Content-Type: application/json' \
--data-raw '{"credentials":{"type":"token","content":{"accessToken":"my-super-super-super-secret-token"}},"id":"gitlab-id","label":"My GitLab Label","type":"gitlab","urls":{"apiBase":"https://gitlab-test.com/api","base":"https://gitlab-test.com"}}'
The JSON schema of the request body
{
"type": "object",
"additionalProperties": false,
"properties": {
"providerId": { "type": "string" },
"label": { "type": "string" },
"description": { "type": "string" },
"type": { "type": "string" },
"capabilities": {
"description": "Field introduced in v10.8 of the Console",
"type": "array",
"items": {
"type": "string",
"enum": ["git-provider", "secret-manager", "ci-cd-tool"],
}
},
"urls": {
"type": "object",
"properties": {
"base": { "type": "string" },
"apiBase": { "type": "string" }
},
"required": ["base", "apiBase"]
},
"base64CA": { "type": "string" },
"proxy": {
"type": "object",
"properties": {
"url": { "type": "string" },
"username": { "type": "string" },
"password": { "type": "string" }
},
"required": ["url"]
},
"credentials": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "token"
},
"expirationDate": {
"description": "Field introduced in v10.8 of the Console",
"type": "string",
"format": "date-time"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"accessToken": { "type": "string" }
},
"required": ["accessToken"]
}
},
"required": ["type", "content"]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "userPass"
},
"expirationDate": {
"description": "Field introduced in v10.8 of the Console",
"type": "string",
"format": "date-time"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"userName": { "type": "string" },
"password": { "type": "string" }
},
"required": ["userName", "password"]
}
},
"required": ["type", "content"]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "m2m"
},
"expirationDate": {
"description": "Field introduced in v10.8 of the Console",
"type": "string",
"format": "date-time"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"accessTokenURL": { "type": "string" },
"token": { "type": "string" }
},
"required": ["accessTokenURL", "token"]
}
},
"required": ["type", "content"]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "client_credentials"
},
"expirationDate": {
"description": "Field introduced in v10.8 of the Console",
"type": "string",
"format": "date-time"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"accessTokenURL": { "type": "string" },
"clientId": { "type": "string" },
"clientSecret": { "type": "string" }
},
"required": ["accessTokenURL", "clientId", "clientSecret"]
}
},
"required": ["type", "content"]
}
]
},
"required": ["providerId", "type", "urls"]
}
}
Supported credential types

As discussed here, different types of providers support different types of credentials. The following table shows the credential types supported by each provider, referring to the data model shown above:

Credentials TypeProviders
tokengitlab, github, bitbucket, azure-devops, vault, jenkins
m2mvault
client_credentialsjenkins
Data model update

The fields capabilities and expirationDate (within credentials) have been introduced starting from version 10.8 of the Console.

Examples of request bodies specific to each provider type are shown below. In the examples, the capabilities and expirationDate fields are omitted, since it is assumed that calls to this API are made by users with a Console version lower than 10.8.

{
"id": "my-github-provider",
"label": "Mia-Platform GitHub",
"type": "github",
"urls": {
"apiBase": "https://api.github.com",
"base": "https://github.com"
},
"credentials": {
"type": "token",
"content": {
"accessToken": "my-super-super-super-secret-token"
}
}
}

PATCH

To edit an existing provider, you need to call the respective API as follows:

curl --location --request PATCH 'https://console-url/api/backend/tenants/my-example-company/providers/gitlab-id' \
--header 'Cookie: sid={{CHANGE_ME_WITH_YOUR_SID}}' \
--header 'Content-Type: application/json' \
--data-raw '{"credentials":{"type":"token","content":{"accessToken":"my-new-super-super-super-secret-token"}}'

The request of this endpoint is identical to the previous one, except that the providerId must be entered inside the endpoint params and not in the request body.