Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

GEL admin API

Enterprise

Grafana Enterprise Logs admin API

NOTE: Admin API version v1 endpoints /admin/api/v1/ are deprecated and will be removed in a future release of GEL. Use the new Admin API version v2 endpoints /admin/api/v2/ instead.

In the following examples, the environment variable API_TOKEN contains the admin token. Refer to Generate an admin token.

It is also possible to create tenants, access policies, and tokens using the plugin.

Tenants

A tenant 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 GEL cluster to which this tenant is scoped. You can only write to or query this tenant from this cluster.

List tenants

GET /admin/api/v1/instances

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint GET /admin/api/v2/tenants instead.

GET /admin/api/v2/tenants

Example:

$ curl -u :$API_TOKEN localhost:3100/admin/api/v2/tenants | jq
{
  "items": [
    {
      "name": "enterprise-logs-dev",
      "display_name": "Enterprise Logs Dev Tenant",
      "created_at": "2021-02-01T17:37:59.341728283Z",
      "status": "active",
      "cluster": "dev-cluster"
    }
  ],
  "type": "tenant"
}

Create a tenant

POST /admin/api/v1/instances

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint POST /admin/api/v2/tenants instead.

POST /admin/api/v2/tenants

Example:

$ curl -u :$API_TOKEN localhost:3100/admin/api/v2/tenants \
--data '{"name":"dev", "display_name":"Dev Tenant", "cluster": "dev-cluster"}'

Update tenant

PUT /admin/api/v1/instances/{name}

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint PUT /admin/api/v2/tenants/{name} instead.

PUT /admin/api/v2/tenants/{name}

Example:

curl -u :$API_TOKEN localhost:3100/admin/api/v2/tenants/enterprise-logs-dev \
-X PUT -H 'If-Match: "123"` \
--data '{"display_name":"Enterprise Logs Dev Tenant", "cluster": "dev-cluster"}' | jq
{
  "name": "enterprise-logs-dev",
  "display_name": "Enterprise Logs Dev Tenant",
  "created_at": "2021-02-01T17:37:59.341728283Z",
  "status": "active",
  "cluster": "dev-cluster"
}

Read tenant details

GET /admin/api/v1/instances/{name}

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint GET /admin/api/v2/tenants/{name} instead.

GET /admin/api/v2/tenants/{name}

Example:

$ curl -u :$API_TOKEN localhost:3100/admin/api/v2/tenants/enterprise-logs-dev | jq
{
  "name": "enterprise-logs-dev",
  "display_name": "Enterprise Logs Dev Tenant",
  "created_at": "2021-02-01T17:37:59.341728283Z",
  "status": "active",
  "cluster": "dev-cluster"
}

Delete a tenant

DELETE /admin/api/v1/instances/{name}

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint DELETE /admin/api/v2/tenants/{name} instead.

DELETE /admin/api/v2/tenants/{name}

Example:

$ curl -X "DELETE" -u :$API_TOKEN localhost:3100/admin/api/v2/tenants/enterprise-logs-dev

Access policies

An access policy is made up of the following fields:

name: The machine-readable name of a policy.
display_name: The human-readable name of a tenant. It can contain any set of characters and can be changed.
created_at: An RFC3339-formatted date time.
realms: A list of realms.
scopes: A list of scopes.

A realm designates the tenant/cluster pairs for which the access policy allows requests:

tenant: You must set this field to an existing tenant or *. *, which denotes access to all tenants.
cluster: You must set this field to an existing cluster.

A scope designates what operations that the tokens, which are assigned to this access policy, are able to perform when calling the GEL API.

logs:read: Permission to view data from a tenant.
logs:write: Permission to write data to a tenant.
logs:delete: Permission to delete data from a tenant.
admin: Permission to perform admin operations.

List access policies

GET /admin/api/v1/accesspolicies

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint GET /admin/api/v2/accesspolicies instead.

GET /admin/api/v2/accesspolicies

Example:

$ curl -u :$API_TOKEN localhost:3100/admin/api/v2/accesspolicies | jq
{
  "items": [
    {
      "name": "ap1",
      "display_name": "First access policy",
      "created_at": "2021-02-01T17:37:59.341728283Z",
      "realms": [
        {
          "tenant": "enterprise-logs-dev",
          "cluster": "dev-cluster"
        }
      ],
      "scopes": [
        "logs:read",
        "logs:write"
      ]
    },
  ],
  "type": "access_policy"
}

Create an access policy

POST /admin/api/v1/accesspolicies

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint POST /admin/api/v2/accesspolicies instead.

POST /admin/api/v2/accesspolicies

$ curl -u :$API_TOKEN localhost:3100/admin/api/v2/accesspolicies \
--data '{"name":"ap1", "display_name":"First access policy", \
  "created_at": "2021-02-01T17:37:59.341728283Z", \
  "realms": [{"tenant": "enterprise-logs-dev", "cluster": "dev-cluster"}], \
  "scopes": ["logs:read", "logs:write"]}'

Update access policy

PUT /admin/api/v1/accesspolicies/{name}

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint PUT /admin/api/v2/accesspolicies/{name} instead.

PUT /admin/api/v2/accesspolicies/{name}

Example:

curl -u :$API_TOKEN localhost:3100/admin/api/v2/accesspolicies/enterprise-logs-dev \
-X PUT -H 'If-Match: "123"` \
--data '{"display_name":"First access policy", \
  "realms": [{"tenant": "enterprise-logs-dev", "cluster": "dev-cluster"}], \
  "scopes": ["logs:read", "logs:write"]}' | jq
{
  "name": "ap1",
  "display_name": "First access policy",
  "created_at": "2021-02-01T17:37:59.341728283Z",
  "realms": [
    {
      "tenant": "enterprise-logs-dev",
      "cluster": "dev-cluster"
    }
  ],
  "scopes": [
    "logs:read",
    "logs:write"
  ]
}

Read an access policy

GET /admin/api/v1/accesspolicies/{name}

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint GET /admin/api/v2/accesspolicies/{name} instead.

GET /admin/api/v2/accesspolicies/{name}

Example:

$ curl -u :$API_TOKEN localhost:3100/admin/api/v2/accesspolicies/ap1 | jq
{
  "name": "ap1",
  "display_name": "First access policy",
  "created_at": "2021-02-01T17:37:59.341728283Z",
  "realms": [
    {
      "tenant": "enterprise-logs-dev",
      "cluster": "dev-cluster"
    }
  ],
  "scopes": [
    "logs:read",
    "logs:write"
  ]
}

Delete an access policy

DELETE /admin/api/v1/accesspolicies/{name}

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint DELETE /admin/api/v2/accesspolicies/{name} instead.

DELETE /admin/api/v2/accesspolicies/{name}

Example:

$ curl -X "DELETE" -u :$API_TOKEN -H 'If-Match: "123"' localhost:3100/admin/api/v2/accesspolicies/ap1

Tokens

A token is made up of the following fields:

name: The machine-readable name of a policy.
display_name: The human-readable name of a tenant. It can contain any set of characters and can be changed.
created_at: An RFC3339-formatted date time.
expiration: An RFC3339-formatted date time.
access_policy: The name of the access policy

Create a token

POST /admin/api/v1/tokens

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint POST /admin/api/v2/tokens instead.

POST /admin/api/v2/tokens

Example:

$ curl -u :$API_TOKEN localhost:3100/admin/api/v2/tokens \
--data '{"name":"devtoken", "display_name":"Dev token", \
  "created_at": "2021-02-01T17:37:59.341728283Z", \
  "expiration": "2021-03-01T17:37:59.341728283Z", \
  "access_policy": "ap1"}'

Read a token

GET /admin/api/v1/tokens/{name}

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint GET /admin/api/v2/tokens/{name} instead.

GET /admin/api/v2/tokens/{name}

Delete a token

DELETE /admin/api/v1/tokens/{name}

Deprecated: this endpoint is deprecated and will be removed in a future release of GEL. Use the endpoint DELETE /admin/api/v2/tokens/{name} instead.

DELETE /admin/api/v2/tokens/{name}

Verify that you can write data to your GEL tenant

The following command pushes a log line by using the Loki API. The TOKEN environment variable contains the preceding token that was created. The value 1612951327316545500 is the current Unix epoch time in nanoseconds at the time of writing; adjust this to the current time. On Linux, you can use the date +%s%N command:

$ date +%s%N
1612951327316545500

Next, the timestamp is used to push a log line:

$ curl -u :$TOKEN localhost:3100/loki/api/v1/push \
-H "Content-Type: application/json" \
-H "X-Scope-OrdID: dev" \
--data '{"streams": [{ "stream": { "job": "example" }, "values": [ [ "1612951327316545500", "A log line" ] ] }]}'

Feedback

Grafana Enterprise Logs admin API

Tenants

List tenants

Create a tenant

Update tenant

Read tenant details

Delete a tenant

Access policies

List access policies

Create an access policy

Update access policy

Read an access policy

Delete an access policy

Tokens

Create a token

Read a token

Delete a token

Verify that you can write data to your GEL tenant

Was this page helpful?

Related documentation

Feedback

Grafana Enterprise Logs admin API

Tenants

List tenants

Create a tenant

Update tenant

Read tenant details

Delete a tenant

Access policies

List access policies

Create an access policy

Update access policy

Read an access policy

Delete an access policy

Tokens

Create a token

Read a token

Delete a token

Verify that you can write data to your GEL tenant

Was this page helpful?

Related documentation

Related resources from Grafana Labs