# API keys

3 calls. Every request needs the `Authorization` header: see [the overview](https://docs.maitento.com/reference.md).

## `apiKeys.list`

```http
GET /users/self/api-keys
```

The caller's API keys (never their secrets).

**Who can call it:** Admins and members, with a portal session (an API key is refused). [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fusers%2Fself%2Fapi-keys).

**Response:** [`UserApiKey`](https://docs.maitento.com/reference/types/user-api-key.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/users/self/api-keys" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const keys = await mt.apiKeys.list();
```
```python title="Python"
mt.api_keys.list()
```

## `apiKeys.create`

```http
POST /users/self/api-keys
```

Creates an API key. The secret is in the response and never shown again. NOTE: `id` in the response is the KEY's id; authenticate with your USER id (`users.self()`): `"<userId>:<secret>"`.

**Who can call it:** Admins and members, with a portal session (an API key is refused). [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fusers%2Fself%2Fapi-keys).

**Request body:** [`UserApiKeyCreateRequest`](https://docs.maitento.com/reference/types/user-api-key-create-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes | A name for the key, 5 to 100 characters, unique among your active keys. |
| `dateExpires` | `datetime \| null` |  | When the key stops working, in UTC; must be in the future. Null: it never expires. |

**Response:** [`UserApiCreateResponse`](https://docs.maitento.com/reference/types/user-api-create-response.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/users/self/api-keys" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"..."}'
```
```ts title="TypeScript"
const { secret } = await mt.apiKeys.create({ name: "ci-deploys" });
```
```python title="Python"
mt.api_keys.create("ci-deploys")
```

## `apiKeys.delete`

```http
DELETE /users/self/api-keys/by-id/{id}
```

Disables an API key.

**Who can call it:** Admins and members, with a portal session (an API key is refused). [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fusers%2Fself%2Fapi-keys%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** no body (204)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/users/self/api-keys/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.apiKeys.delete("8d7c6b5a-4f3e-4d2c-9b1a-0f9e8d7c6b5a");
```
```python title="Python"
mt.api_keys.delete("6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c")
```