API Keys

Model

Fields

Field

Type

Description
object
"key"
id
string
last4
string The last four characters of the key, for telling keys apart. The full secret is only returned at creation.
created_at
updated_at
scopes
What the key may do: each resource mapped to its allowed actions (read, write, delete).
team_id
string
name
string
updated_by
string | null Who last changed the key, including at creation.
last_used_at
| null When the key last authenticated a request, accurate to five minutes. Null until it is used. A key created before Tailglow began recording key use shows null until its next request.

List API Keys

Endpoint

Retrieve a list of API keys for the current team.

keys:read
GET
/v1/keys

Query Parameters

Field

Type

Description
order_by
string Field used to order the API keys. Defaults to "created_at". Accepted values: "created_at","name".
limit
number Maximum number of items to return. Defaults to 25. Minimum: 1. Maximum: 200.
after
string Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string Sort direction for the result set. Defaults to "desc". Accepted values: "asc","desc".

Comments

  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: Key[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve API Key

Endpoint

Retrieve a single API key.

keys:read
GET
/v1/keys/:key_id

Path Parameters

Field

Type

Description
key_id
string Unique identifier of the key.

Response

200 
{
  message: string;
  data: Key;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Create API Key

Endpoint

Create a new API key for the current team.

keys:write
POST
/v1/keys

Request Body

Field

Type

Requirement

Description
name
string
Required
Display name for the API key. Minimum length: 2. Maximum length: 60.
scopes
Optional
Scope names mapped to their permitted actions. Allowed scope keys: "users", "roles", "keys", "records", "projects", "metrics", "views", "billing", "pages", "monitors", "alerts", "chats", "secrets", "servers", "ingest_keys", "sources", "domains", "facets", "drains", "pulls", "checks", "logs". Allowed action values: "read", "write", "delete".

Comments

  • You can assign only scopes that your own authorization has.

Response

201 
{
  message: string;
  data: Key & { api_key: string };
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}

Additional Response Fields

Field

Type
api_key
string

Update API Key

Endpoint

Update an existing API key.

keys:write
POST
/v1/keys/:key_id

Path Parameters

Field

Type

Description
key_id
string Unique identifier of the key.

Request Body

Field

Type

Requirement

Description
name
string
Optional
Display name for the API key.
scopes
Optional
Scope names mapped to their permitted actions. Allowed scope keys: "users", "roles", "keys", "records", "projects", "metrics", "views", "billing", "pages", "monitors", "alerts", "chats", "secrets", "servers", "ingest_keys", "sources", "domains", "facets", "drains", "pulls", "checks", "logs". Allowed action values: "read", "write", "delete".

Comments

  • You can assign only scopes that your own authorization has.

Response

200 
{
  message: string;
  data: Key;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Delete API Key

Endpoint

Delete an API key from the current team.

DELETE
/v1/keys/:key_id

Path Parameters

Field

Type

Description
key_id
string Unique identifier of the key.

Comments

  • Deleting a key needs keys:delete, except that a key can always delete itself. tglow logout uses this to remove the key it signed in with.

Response

200 
{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Referenced Types

Scopes

Record<string, ("read" | "write" | "delete")[]>

Scope names mapped to their permitted actions. Allowed scope keys: "users", "roles", "keys", "records", "projects", "metrics", "views", "billing", "pages", "monitors", "alerts", "chats", "secrets", "servers", "ingest_keys", "sources", "domains", "facets", "drains", "pulls", "checks", "logs". Allowed action values: "read", "write", "delete".

ISODateString

An ISO 8601 date-time string returned at the JSON API boundary.

Scope

users
roles
keys
records
projects
metrics
views
billing
pages
monitors
alerts
chats
secrets
servers
ingest_keys
sources
domains
facets
drains
pulls
checks
logs

ScopeValue

read
write
delete