# API Keys

## API Key Model

### Fields

- **`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`** [`ISODateString`](/api/keys#iso-date-string)

- **`updated_at`** [`ISODateString`](/api/keys#iso-date-string)

- **`scopes`** [`Scopes`](/api/keys#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`** [`ISODateString | null`](/api/keys#iso-date-string)

   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.

### 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

`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"`

## List API Keys

### Endpoint

Retrieve a list of API keys for the current team.

```http
GET /v1/keys
```

**Scope:** `keys:read`

### Query Parameters

- **`order_by`** `string`
  Field used to order the API keys. Optional. Defaults to `"created_at"`. Allowed values: `"created_at"`, `"name"`.

- **`limit`** `number`
  Maximum number of items to return. Optional. Defaults to `25`. Minimum: `1`. Maximum: `200`.

- **`after`** `string`
  Cursor from `pagination.next_cursor` of a previous response. Returns the resources after that page. Optional.

- **`before`** `string`
  Cursor from `pagination.prev_cursor` of a previous response. Returns the resources before that page. Optional.

- **`sort`** `string`
  Sort direction for the result set. Optional. Defaults to `"desc"`. Allowed values: `"asc"`, `"desc"`.

### Response

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

### Comments

- `after` and `before` are mutually exclusive.

## Retrieve API Key

### Endpoint

Retrieve a single API key.

```http
GET /v1/keys/:key_id
```

**Scope:** `keys:read`

### Path Parameters

- **`key_id`** `string` -- **Required**
  Unique identifier of the key.

### Response

Key retrieved

```ts
{
  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.

```http
POST /v1/keys
```

**Scope:** `keys:write`

### Request Body

- **`name`** `string` -- **Required**
  Display name for the API key. Minimum length: `2`. Maximum length: `60`.

- **`scopes`** [`Scopes`](/api/keys#scopes)
  Scope names mapped to their permitted actions. Optional. 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"`.

### Response

You'll only be able to see your API key one time.

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

#### Additional Response Fields

- **`api_key`** `string` -- **Required**
  The full API key. Returned once, when the key is created, and never again. Store it at that point; afterwards only `last4` is available.

### Comments

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

## Update API Key

### Endpoint

Update an existing API key.

```http
POST /v1/keys/:key_id
```

**Scope:** `keys:write`

### Path Parameters

- **`key_id`** `string` -- **Required**
  Unique identifier of the key.

### Request Body

- **`name`** `string`
  Display name for the API key. Optional.

- **`scopes`** [`Scopes`](/api/keys#scopes)
  Scope names mapped to their permitted actions. Optional. 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"`.

### Response

Your API key has been updated.

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

### Comments

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

## Delete API Key

### Endpoint

Delete an API key from the current team.

```http
DELETE /v1/keys/:key_id
```

### Path Parameters

- **`key_id`** `string` -- **Required**
  Unique identifier of the key.

### Response

Your API key has been deleted.

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

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