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 license information

Retrieves 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
  }
}

List all licenses

Lists 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 a license

Retrieves information about a specified 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
  }
}

Create a license

Creates 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

Deletes a specified 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

Triggers recalculation of billable users for a specified license.

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 license usage information

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