License API

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed, GitLab Dedicated

Use this API to interact with license endpoints. For more information, see activate GitLab EE with a license file or key.

Prerequisites:

You must have administrator access to the instance.

Retrieve information about the current license

GET /license

{
  "id": 2,
  "plan": "ultimate",
  "created_at": "2018-02-27T23:21:58.674Z",
  "starts_at": "2018-01-27",
  "expires_at": "2022-01-27",
  "historical_max": 300,
  "maximum_user_count": 300,
  "expired": false,
  "overage": 200,
  "user_limit": 100,
  "active_users": 300,
  "licensee": {
    "Name": "John Doe1",
    "Email": "johndoe1@gitlab.com",
    "Company": "GitLab"
  },
  "add_ons": {
    "GitLab_FileLocks": 1,
    "GitLab_Auditor_User": 1
  }
}

Retrieve information about all licenses

GET /licenses

[
  {
    "id": 1,
    "plan": "premium",
    "created_at": "2018-02-27T23:21:58.674Z",
    "starts_at": "2018-01-27",
    "expires_at": "2022-01-27",
    "historical_max": 300,
    "maximum_user_count": 300,
    "expired": false,
    "overage": 200,
    "user_limit": 100,
    "licensee": {
      "Name": "John Doe1",
      "Email": "johndoe1@gitlab.com",
      "Company": "GitLab"
    },
    "add_ons": {
      "GitLab_FileLocks": 1,
      "GitLab_Auditor_User": 1
    }
  },
  {
    "id": 2,
    "plan": "ultimate",
    "created_at": "2018-02-27T23:21:58.674Z",
    "starts_at": "2018-01-27",
    "expires_at": "2022-01-27",
    "historical_max": 300,
    "maximum_user_count": 300,
    "expired": false,
    "overage": 200,
    "user_limit": 100,
    "licensee": {
      "Name": "Doe John",
      "Email": "doejohn@gitlab.com",
      "Company": "GitLab"
    },
    "add_ons": {
      "GitLab_FileLocks": 1
    }
  }
]

Overage is the difference between the number of billable users and the licensed number of users. This is calculated differently depending on whether the license has expired or not.

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.

Returns:

200 OK with response containing the licenses in JSON format. This is an empty JSON array if there are no licenses.
403 Forbidden if the current user in not permitted to read the licenses.

Retrieve information about a single license

GET /license/:id

Supported attributes:

Attribute	Type	Required	Description
`id`	integer	yes	ID of the GitLab license.

Returns the following status codes:

200 OK: Response contains the licenses in JSON format.
404 Not Found: The requested license doesn’t exist.
403 Forbidden: The current user is not permitted to read the licenses.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/license/:id"

Example response:

{
  "id": 1,
  "plan": "premium",
  "created_at": "2018-02-27T23:21:58.674Z",
  "starts_at": "2018-01-27",
  "expires_at": "2022-01-27",
  "historical_max": 300,
  "maximum_user_count": 300,
  "expired": false,
  "overage": 200,
  "user_limit": 100,
  "active_users": 50,
  "licensee": {
    "Name": "John Doe1",
    "Email": "johndoe1@gitlab.com",
    "Company": "GitLab"
  },
  "add_ons": {
    "GitLab_FileLocks": 1,
    "GitLab_Auditor_User": 1
  }
}

Add a new license

POST /license

Attribute	Type	Required	Description
`license`	string	yes	The license string

curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/license?license=eyJkYXRhIjoiMHM5Q...S01Udz09XG4ifQ=="

Example response:

{
  "id": 1,
  "plan": "ultimate",
  "created_at": "2018-02-27T23:21:58.674Z",
  "starts_at": "2018-01-27",
  "expires_at": "2022-01-27",
  "historical_max": 300,
  "maximum_user_count": 300,
  "expired": false,
  "overage": 200,
  "user_limit": 100,
  "active_users": 300,
  "licensee": {
    "Name": "John Doe1",
    "Email": "johndoe1@gitlab.com",
    "Company": "GitLab"
  },
  "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

DELETE /license/:id

Attribute	Type	Required	Description
`id`	integer	yes	ID of the GitLab license.

curl --request DELETE \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/license/:id"

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.

Trigger recalculation of billable users

PUT /license/:id/refresh_billable_users

Attribute	Type	Required	Description
`id`	integer	yes	ID of the GitLab license.

curl --request PUT \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/license/:id/refresh_billable_users"

Example response:

{
  "success": true
}

Returns:

202 Accepted if the request to refresh billable users is successfully initiated.
403 Forbidden if the current user in not permitted to refresh billable users for the license.
404 Not Found if the license could not be found.

Attribute	Type	Description
`success`	boolean	Whether the request succeeded or not.

Retrieve usage information about the current license

Gets usage information about the current license and exports it in CSV format.

GET /license/usage_export.csv

curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/license/usage_export.csv"

Example response:

License Key,"eyJkYXRhIjoib1EwRWZXU3RobDY2Yl=
"
Email,user@example.com
License Start Date,2023-02-22
License End Date,2024-02-22
Company,Example Corp.
Generated At,2023-09-05 06:56:23
"",""
Date,Billable User Count
2023-07-11 12:00:05,21
2023-07-13 12:00:06,21
2023-08-16 12:00:02,21
2023-09-04 12:00:12,21

Returns:

200 OK: Response contains the license usage in CSV format.
403 Forbidden if the current user in not permitted to view license usage.