--- title: "GEM Admin API | Grafana Enterprise Metrics documentation" description: "GEM Admin API NOTE: Admin API version v1 /admin/api/v1/ and v2 /admin/api/v2/ endpoints are deprecated and will be removed in a future release of GEM. Use the new Admin API version v3 endpoints /admin/api/v3/ instead." --- # GEM Admin API > **NOTE:** Admin API version v1 /admin/api/v1/ and v2 /admin/api/v2/ endpoints are deprecated and will be removed in a future release of GEM. Use the new Admin API version v3 endpoints /admin/api/v3/ instead. In addition to the standard [Grafana Mimir API endpoints](/docs/enterprise-metrics/latest/api/mimir-api/), Grafana Enterprise Metrics supports an admin HTTP API for managing cluster resources such as tenants and tokens. ## API operations The API supports standard CRUD (create, read, update, and delete) operations for most resources. Creates are issued via `POST` requests, reads via `GET` requests, updates via `PUT` requests, and deletes via `DELETE` requests. When running multiple instances of the Admin API, we recommend that you enable leader election so that all mutations occur on a single, leader-elected instance. ### Write consistency (If-Match and ETag headers) To ensure concurrent changes are propagated in a way that avoids unintentional overwrites, an [`If-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header is required for all requests that mutate data. The current version of a resource to be sent in the `If-Match` header can be found in the [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header returned on all `GET` and `PUT` requests that return a single resource in the response body. Here are a few examples of how to get the value of the `ETag` header using `curl`. The first example uses the argument `-D -` to write all headers to standard out, and then parses for the `ETag` header. console ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```console curl -u :$API_TOKEN -sD - -o /dev/null http://localhost:8080/admin/api/v3/accesspolicies/{name} | grep -i ETag | cut -d " " -f 2 ``` This second example uses the `-i` option to print the headers along with the response payload. console ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```console curl -u :$API_TOKEN -i http://localhost:8080/admin/api/v3/accesspolicies/{name} ``` When making a request to mutate data, make sure to include the double quotes (`"`) around the value in the `If-Match` header. So, for example, the following is a request to update the access policy named `the-access-policy`, currently at version `1`: console ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```console curl -u :$API_TOKEN -X PUT -H 'If-Match: "1"' http://localhost:8080/admin/api/v3/accesspolicies/the-access-policy --data '{"status": "active", "realms": [{"tenant": "enterprise-metrics-dev", "cluster": "enterprise-metrics-dev"}], "scopes": ["metrics:write"]}' ``` Optionally, a wildcard `"*"` may be passed as the `If-Match` version which effectively disables the write consistency protections and allows any current version to be updated. ## Cluster API ### List clusters `GET /admin/api/v1/clusters` `GET /admin/api/v2/clusters` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `GET /admin/api/v3/clusters` instead. `GET /admin/api/v3/clusters` Response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "items": [ { "name": "", // cluster name "display_name": "", // cluster display name "created_at": "", // date created "kind": "", // cluster type, currently only cortex is supported "base_url": "" // Base URL of the cluster, optional } ... ], "type": "cluster" } ``` Example: console ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```console $ curl -u :$API_TOKEN http://localhost:8080/admin/api/v3/clusters | jq { "items": [ { "name": "enterprise-metrics-dev", "display_name": "enterprise-metrics-dev", "created_at": "2020-07-13T16:50:41.953793Z", "kind": "metrics", "base_url": "" } ], "type": "cluster" } ``` ### Get cluster `GET /admin/api/v1/clusters/{name}` `GET /admin/api/v2/clusters/{name}` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `GET /admin/api/v3/clusters/{name}` instead. `GET /admin/api/v3/clusters/{name}` NOTES: - There is no `ETag` header on a cluster response because clusters are immutable. Response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "name": "", // cluster name "display_name": "", // cluster display name "created_at": "", // date created "kind": "", // cluster type, currently only cortex is supported "base_url": "" // Base URL of the cluster, optional } ``` Example: console ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```console $ curl -u :$API_TOKEN http://localhost:8080/admin/api/v3/clusters/enterprise-metrics-dev | jq { "name": "enterprise-metrics-dev", "display_name": "enterprise-metrics-dev", "created_at": "2020-07-13T16:50:41.953793Z", "kind": "metrics", "base_url": "" } ``` ## Tenant API ### Model The tenant model is made up of the following fields: - `name`: The machine-readable name of a tenant. It must be between 3 and 64 characters and only include the following characters, `[a-z0-9-_]`. Once set, this field is immutable. - `display_name`: The human-readable name of a tenant. It can contain any set of characters and can be changed. - `status`: The current status of this tenant. It can have the following values: - `active` - `inactive` - `unknown` - `cluster`: The name of the Grafana Enterprise Metrics cluster that this tenant is scoped to. You will only be able to write/query this tenant from this cluster. - `limits`: Tenant-specific resource usage limits. Limits are key-value pairs (JSON object) that correspond to [Grafana Mimir limits configuration](/docs/mimir/v2.17.x/configure/configuration-parameters/#limits). **Deprecated**: The `limits` field is deprecated and set to be removed in a future release of GEM. Set this field to `limits: null` or remove it from your configuration. Instead, define limits using [runtime configuration in Grafana Mimir](/docs/mimir/v2.17.x/configure/about-runtime-configuration/). For information on how to migrate limit settings to runtime configuration, refer to [Migrate your limits configuration](/docs/enterprise-metrics/latest/configure/config-gem/limits/#migrate-your-limits-configuration). ### List tenants `GET /admin/api/v1/instances` `GET /admin/api/v2/tenants` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `GET /admin/api/v3/tenants` instead. `GET /admin/api/v3/tenants` NOTES: - This endpoint only returns tenants in an `active` status. To get all tenants including `inactive` ones use the query parameter `include-non-active=true` Response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "items": [ { "name": "", "display_name": "", "created_at": "", "status": "", "cluster": "" }, ... ], "type": "tenant" } ``` Example: console ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```console $ curl -u :$API_TOKEN localhost:8080/admin/api/v3/tenants | jq { "items": [ { "name": "enterprise-metrics-dev", "display_name": "Grafana Enterprise Metrics dev tenant", "created_at": "2020-07-13T17:37:59.341728283Z", "status": "active", "cluster": "enterprise-metrics-dev" } ], "type": "tenant" } ``` ### Create tenant `POST /admin/api/v1/instances` `POST /admin/api/v2/tenants` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `POST /admin/api/v3/tenants` instead. `POST /admin/api/v3/tenants` NOTES: - Because tenant names are unique, you cannot create a new tenant with the same name as a tenant that already exists but is in the `inactive` state. Instead, to use the same tenant name again you must re-enable the `inactive` tenant by updating its state to `active`. To make this change, use the [Update Tenant](#update-tenant) endpoint. When creating a tenant via this API call, it is not required to specify the `status` field because the status is always overwritten by the API to `active`. Example: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none $ curl -u :$API_TOKEN -X POST localhost:8080/admin/api/v3/tenants --data-raw ' { "name": "enterprise-metrics-dev", "display_name": "Grafana Enterprise Metrics dev tenant", "created_at": "2020-07-13T17:37:59.341728283Z", "status": "active", "cluster": "enterprise-metrics-dev" }' ``` Response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "name": "enterprise-metrics-dev", "display_name": "Grafana Enterprise Metrics dev tenant", "created_at": "2020-07-13T17:37:59.341728283Z", "status": "active", "cluster": "enterprise-metrics-dev" } ``` ### Update tenant `PUT /admin/api/v1/instances/{name}` `PUT /admin/api/v2/tenants/{name}` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `PUT /admin/api/v3/tenants/{name}` instead. `PUT /admin/api/v3/tenants/{name}` NOTES: - The `name` field of the object in the request body is ignored during updates. - The `created_at` field may not be modified during updates. - `If-Match` header matching the current version is required. Response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "name": "", "display_name": "", "created_at": "", "status": "", "cluster": "" } ``` Example: console ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```console curl -u :$API_TOKEN localhost:8080/admin/api/v3/tenants/enterprise-metrics-dev \ -X PUT -H 'If-Match: "123"` \ --data '{"display_name":"Grafana Enterprise Metrics dev tenant", "status": "active", "cluster": "enterprise-metrics-dev"}' | jq { "name": "enterprise-metrics-dev", "display_name": "Grafana Enterprise Metrics dev tenant", "created_at": "2020-07-13T17:37:59.341728283Z", "status": "active", "cluster": "enterprise-metrics-dev" } ``` ### Get tenant `GET /admin/api/v1/instances/{name}` `GET /admin/api/v2/tenants/{name}` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `GET /admin/api/v3/tenants/{name}` instead. `GET /admin/api/v3/tenants/{name}` NOTES: - The current version of the tenant will be returned in an `ETag` header on the response. Response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "name": "", "display_name": "", "created_at": "", "status": "", "cluster": "" } ``` Example: console ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```console $ curl -u :$API_TOKEN localhost:8080/admin/api/v3/tenants/enterprise-metrics-dev | jq { "name": "enterprise-metrics-dev", "display_name": "Grafana Enterprise Metrics dev tenant", "created_at": "2020-07-13T17:37:59.341728283Z", "status": "active", "cluster": "enterprise-metrics-dev" } ``` ### Delete tenant `DELETE /admin/api/v1/instances/{name}` `DELETE /admin/api/v2/instances/{name}` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. In Admin API version v3, delete operations are no longer supported and have been replaced by soft deletes. Use the endpoint `PUT /admin/api/v3/tenants/{name}` with `"status": "inactive"` instead. This operation will inactivate a tenant and subsequent HTTP requests for the tenant will fail with a 401 Unauthorized HTTP status code. To re-enable a tenant, use the endpoint `PUT /admin/api/v3/tenants/{name}` with `"status": "active"`. `PUT /admin/api/v3/tenants/{name}` JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "inactive", "cluster": "" } ``` NOTES: - `If-Match` header matching the current version is required. Example: console ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```console curl -u :$API_TOKEN localhost:8080/admin/api/v3/tenants/enterprise-metrics-dev \ -X PUT -H 'If-Match: "123"` \ --data '{"status": "inactive", "cluster": "enterprise-metrics-dev"}' | jq { "name": "enterprise-metrics-dev", "display_name": "Grafana Enterprise Metrics dev tenant", "created_at": "2020-07-13T17:37:59.341728283Z", "status": "inactive", "cluster": "enterprise-metrics-dev" } ``` ## Access policy API ### List access policies `GET /admin/api/v1/accesspolicies` `GET /admin/api/v2/accesspolicies` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `GET /admin/api/v3/accesspolicies` instead. `GET /admin/api/v3/accesspolicies` NOTES: - This endpoint only returns access policies in an `active` status. To get all access policies including `inactive` ones use the query parameter `include-non-active=true` Response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "items": [ { "name": "", "display_name": "", "created_at": "", "status": "", "realms": [ { "tenant": "", "cluster": "" } ], "scopes": [ "", ... ] }, ... ], "type": "access_policy" } ``` ### Create access policy `POST /admin/api/v1/accesspolicies` `POST /admin/api/v2/accesspolicies` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `POST /admin/api/v3/accesspolicies` instead. `POST /admin/api/v3/accesspolicies` Payload: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "name": "", "display_name": "", "created_at": "", "realms": [ { "tenant": "", "cluster": "" } ], "scopes": [ "", ... ] } ``` Because access policy names are unique, you cannot create a new access policy with the same name as an access policy that already exists but is in the `inactive` state. Instead, to use the same access policy name again you must re-enable the `inactive` access policy by updating its state to `active`. To make this change, use the [Update Access Policy](#update-access-policy) endpoint. When creating an access policy via this API call, it is not required to specify the `status` field because the status is always overwritten by the API to `active`. #### Realms Realms designate the tenant/cluster pairs that the access policy allows requests for: - `tenant`: This field must be set to an existing tenant or `*`. `*` denotes access to all tenants. - `cluster`: This field must be set to an existing cluster. - `label_policies`: This is an optional field that can be set to a list of label policies. An access policy gets access to metrics that match at least one of the label policies. If label policies are not set, all metrics will match. ##### Label policy, selector, and label matchers A label policy contains a selector that’s a PromQL metric selector string: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "selector": "" } ``` The PromQL metric selector `{job="grafana-labs", role!="software-engineer"}` translates into this label policy: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "selector": "{job=\"grafana-labs\", role!=\"software-engineer\"}" } ``` #### Scopes Scopes designate what operations tokens assigned to this access policy will be able to do when calling the GEM API. - `admin`: Permission to perform admin operations - `admin:read`: Permission to view admin resources (access policies and tokens, tenants, and clusters) - `alerts:read`: Permission to view the Alertmanager UI and get the Alertmanager configuration for a tenant - `alerts:write`: Permission to create silences in the Alertmanager UI and create and delete the Alertmanager configuration for a tenant - `metrics:delete`: Permission to delete data from a tenant - `metrics:read`: Permission to view data from a tenant - `metrics:write`: Permission to write data to a tenant - `rules:read`: Permission to read ruler rules - `rules:write`: Permission to write ruler rules ### Update access policy `PUT /admin/api/v1/accesspolicies/{name}` `PUT /admin/api/v2/accesspolicies/{name}` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `PUT /admin/api/v3/accesspolicies/{name}` instead. `PUT /admin/api/v3/accesspolicies/{name}` NOTES: - `If-Match` header matching the current version is required. - Update differs from create in that only the `Display Name`, `Status`, [`Realms`](#realms), and [`Scopes`](#scopes) are updatable. Payload: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "display_name": "", "status": "", "realms": [ { "tenant": "", "cluster": "" } ], "scopes": [ "", ... ] } ``` ### Get access policy `GET /admin/api/v1/accesspolicies/{name}` `GET /admin/api/v2/accesspolicies/{name}` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `GET /admin/api/v3/accesspolicies/{name}` instead. `GET /admin/api/v3/accesspolicies/{name}` NOTES: - The current version of the access policy will be returned in an `ETag` header on the response. Response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "name": "", "display_name": "", "created_at": "", "status": "", "realms": [ { "tenant": "", "cluster": "" } ], "scopes": [ "", ... ] } ``` ### Delete access policy `DELETE /admin/api/v1/accesspolicies/{name}` `DELETE /admin/api/v2/accesspolicies/{name}` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. In Admin API version v3, delete operations are no longer supported and have been replaced by soft deletes. Use the endpoint `PUT /admin/api/v3/accesspolicies/{name}` with `"status": "inactive"` instead. This operation will inactivate an access policy and subsequent HTTP requests with an associated token will fail with a 401 Unauthorized HTTP status code. To re-enable an access policy, use the endpoint `PUT /admin/api/v3/accesspolicies/{name}` with `"status": "active"`. `PUT /admin/api/v3/accesspolicies/{name}` NOTES: - `If-Match` header matching the current version is required. Example: console ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```console curl -u :$API_TOKEN localhost:8080/admin/api/v3/tokens/accesspolicies/enterprise-metrics-ap \ -X PUT -H 'If-Match: "123"` \ --data '{"status": "inactive", "realms": [{"tenant": "enterprise-metrics-dev", "cluster": "enterprise-metrics-dev"}], "scopes": ["metrics:write"]}' | jq { "name": "enterprise-metrics-ap", "created_at": "2022-02-11T16:55:43.598543386Z", "status": "inactive", "realms": [ { "tenant": "enterprise-metrics-dev", "cluster": "enterprise-metrics-dev" } ], "scopes": [ "metrics:write" ] } ``` ## Token API ### List tokens `GET /admin/api/v1/tokens` `GET /admin/api/v2/tokens` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `GET /admin/api/v3/tokens` instead. `GET /admin/api/v3/tokens` NOTES: - This endpoint only returns tokens in an `active` status. To get all tokens including `inactive` ones use the query parameter `include-non-active=true` Response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "items": [ { "name": "", "display_name": "", "created_by": "", "created_at": "", "status": "", "access_policy": "", "expiration": "" }, ... ], "type": "token" } ``` ### Create token `POST /admin/api/v1/tokens` `POST /admin/api/v2/tokens` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `POST /admin/api/v3/tokens` instead. `POST /admin/api/v3/tokens` Payload: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "name": "", "display_name": "", "created_at": "", "access_policy": "", "expiration": "" } ``` Because token names are unique, you cannot create a new token with the same name as a token that already exists but is in the `inactive` state. Instead, to use the same token name again you must re-enable the `inactive` token by updating its state to `active`. To make this change, use the `PUT /admin/api/v3/tokens/{name}` endpoint. When creating a token via this API call, it is not required to specify the `status` field because the status is always overwritten by the API to `active`. ### Get token `GET /admin/api/v1/tokens/{name}` `GET /admin/api/v2/tokens/{name}` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `GET /admin/api/v3/tokens/{name}` instead. `GET /admin/api/v3/tokens/{name}` NOTES: - The current version of the token will be returned in an `ETag` header on the response. Response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "name": "", "display_name": "", "created_at": "", "status": "", "access_policy": "", "expiration": "" } ``` ### Delete token `DELETE /admin/api/v1/tokens/{name}` `DELETE /admin/api/v2/tokens/{name}` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. In Admin API version v3, delete operations are no longer supported and have been replaced by soft deletes. Use the endpoint `PUT /admin/api/v3/tokens/{name}` with `"status": "inactive"` instead. This operation will inactivate a token and subsequent HTTP requests with the token will fail with a 401 Unauthorized HTTP status code. To re-enable a token, use the endpoint `PUT /admin/api/v3/tokens/{name}` with `"status": "active"`. `PUT /admin/api/v3/tokens/{name}` JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "inactive" } ``` NOTES: - `If-Match` header matching the current version is required. Example: console ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```console curl -u :$API_TOKEN localhost:8080/admin/api/v3/tokens/enterprise-metrics-token \ -X PUT -H 'If-Match: "123"` \ --data '{"status": "inactive"}' | jq { "name": "enterprise-metrics-token", "display_name": "Grafana Enterprise Metrics Dev Token", "created_at": "2022-02-11T16:59:36.275826382Z", "status": "inactive", "access_policy": "enterprise-metrics-ap", "expiration": "2050-01-01T00:00:00Z" } ``` ## License API ### List licenses `GET /admin/api/v1/licenses` `GET /admin/api/v2/licenses` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `GET /admin/api/v3/licenses` instead. `GET /admin/api/v3/licenses` Response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "items": [ { "name": "", "display_name": "", "created_by": "", "created_at": "", "token": { "jti": "", "iss": "", "sub": "", "iat": "", "exp": "", "nbf": "", "lexp": "", "lid": "", "max_users": "", "included_admins": "", "included_viewers": "", "lic_exp_warn_days": "", "prod": [ "", ... ], "company": "", "slug": "", } }, ... ], "type": "license" } ``` ## Feature detection API ### Get product and feature information `GET /admin/api/v1/features` `GET /admin/api/v2/features` **Deprecated**: these endpoints are deprecated and will be removed in a future release of GEM. Use the endpoint `GET /admin/api/v3/features` instead. `GET /admin/api/v3/features` Response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "name": "", "version": "", "features": { "": "", ... } } ``` Example response: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "name": "GEM", "version": "1.1", "features": { "debug_export": "v1", "editable_access_policies": "v1", "editable_tenants": "v1", "lbac": "v1", "self_monitoring": "v1", "federated_rules": "v1" } } ```