debian-mirror-gitlab/doc/api/license.md

187 lines
4.1 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
stage: none
group: unassigned
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2021-01-29 00:20:46 +05:30
---
2019-09-30 21:07:59 +05:30
# License **(CORE ONLY)**
2019-09-04 21:01:54 +05:30
2021-01-03 14:25:43 +05:30
To interact with license endpoints, you need to authenticate yourself as an
2021-02-22 17:27:13 +05:30
administrator.
2019-09-04 21:01:54 +05:30
## Retrieve information about the current license
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
GET /license
```
```json
{
"id": 2,
"plan": "gold",
"created_at": "2018-02-27T23:21:58.674Z",
"starts_at": "2018-01-27",
"expires_at": "2022-01-27",
"historical_max": 300,
2019-12-26 22:10:19 +05:30
"maximum_user_count": 300,
2019-09-04 21:01:54 +05:30
"expired": false,
"overage": 200,
"user_limit": 100,
"active_users": 300,
"licensee": {
"Name": "John Doe1"
},
"add_ons": {
"GitLab_FileLocks": 1,
"GitLab_Auditor_User": 1
}
}
```
## Retrieve information about all licenses
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
GET /licenses
```
```json
[
{
"id": 1,
"plan": "silver",
"created_at": "2018-02-27T23:21:58.674Z",
"starts_at": "2018-01-27",
"expires_at": "2022-01-27",
"historical_max": 300,
2019-12-26 22:10:19 +05:30
"maximum_user_count": 300,
2019-09-04 21:01:54 +05:30
"expired": false,
"overage": 200,
"user_limit": 100,
"licensee": {
"Name": "John Doe1"
},
"add_ons": {
"GitLab_FileLocks": 1,
"GitLab_Auditor_User": 1
}
},
{
"id": 2,
"plan": "gold",
"created_at": "2018-02-27T23:21:58.674Z",
"starts_at": "2018-01-27",
"expires_at": "2022-01-27",
"historical_max": 300,
2019-12-26 22:10:19 +05:30
"maximum_user_count": 300,
2019-09-04 21:01:54 +05:30
"expired": false,
"overage": 200,
"user_limit": 100,
"licensee": {
"Name": "Doe John"
},
"add_ons": {
"GitLab_FileLocks": 1,
}
}
]
```
2021-02-22 17:27:13 +05:30
Overage is the difference between the number of billable users and the licensed number of users.
2019-09-04 21:01:54 +05:30
This is calculated differently depending on whether the license has expired or not.
2021-02-22 17:27:13 +05:30
- If the license has expired, it uses the historical maximum billable user count (`historical_max`).
- If the license has not expired, it uses the current billable users count.
2019-09-04 21:01:54 +05:30
Returns:
2021-02-22 17:27:13 +05:30
- `200 OK` with response containing the licenses in JSON format. This is an empty JSON array if there are no licenses.
2019-09-04 21:01:54 +05:30
- `403 Forbidden` if the current user in not permitted to read the licenses.
## Add a new license
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
POST /license
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `license` | string | yes | The license string |
2020-03-13 15:44:24 +05:30
```shell
2019-09-04 21:01:54 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/license?license=eyJkYXRhIjoiMHM5Q...S01Udz09XG4ifQ=="
```
Example response:
```json
{
"id": 1,
"plan": "gold",
"created_at": "2018-02-27T23:21:58.674Z",
"starts_at": "2018-01-27",
"expires_at": "2022-01-27",
"historical_max": 300,
2019-12-26 22:10:19 +05:30
"maximum_user_count": 300,
2019-09-04 21:01:54 +05:30
"expired": false,
"overage": 200,
"user_limit": 100,
"active_users": 300,
"licensee": {
"Name": "John Doe1"
},
"add_ons": {
"GitLab_FileLocks": 1,
"GitLab_Auditor_User": 1
}
}
```
Returns:
- `201 Created` if the license is successfully added.
- `400 Bad Request` if the license couldn't be added, with an error message explaining the reason.
## Delete a license
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-04 21:01:54 +05:30
DELETE /license/:id
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | ID of the GitLab license. |
2020-03-13 15:44:24 +05:30
```shell
2019-09-04 21:01:54 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/license/:id"
```
Example response:
```json
{
"id": 2,
"plan": "gold",
"created_at": "2018-02-27T23:21:58.674Z",
"starts_at": "2018-01-27",
"expires_at": "2022-01-27",
"historical_max": 300,
2019-12-26 22:10:19 +05:30
"maximum_user_count": 300,
2019-09-04 21:01:54 +05:30
"expired": false,
"overage": 200,
"user_limit": 100,
"licensee": {
"Name": "John Doe"
},
"add_ons": {
"GitLab_FileLocks": 1,
"GitLab_Auditor_User": 1
}
}
```
Returns:
- `204 No Content` if the license is successfully deleted.
- `403 Forbidden` if the current user in not permitted to delete the license.
- `404 Not Found` if the license to delete could not be found.