# Secrets

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

## `secrets.list`

```http
GET /secrets
```

Every secret (names only, never values).

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

**Response:** [`Secret`](https://docs.maitento.com/reference/types/secret.md)`[]` (200)

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

## `secrets.create`

```http
POST /secrets
```

Creates a secret.

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

**Request body:** [`SecretCreateRequest`](https://docs.maitento.com/reference/types/secret-create-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes | The secret's name, which definitions use to refer to it. |
| `value` | `string` | yes | The secret value, kept exactly as sent (whitespace included). It is never returned. |

**Response:** [`Secret`](https://docs.maitento.com/reference/types/secret.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/secrets" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"...","value":"..."}'
```
```ts title="TypeScript"
const secret = await mt.secrets.create({ name: "orders-api-key", value: process.env.ORDERS_API_KEY! });
```
```python title="Python"
mt.secrets.create("orders-api-key", os.environ["ORDERS_API_KEY"])
```

## `secrets.delete`

```http
DELETE /secrets/by-id/{id}
```

Deletes a secret.

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

**Path parameters**

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

**Response:** no body (200)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/secrets/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.secrets.delete("c0ffee00-1234-4abc-9def-0123456789ab");
```
```python title="Python"
mt.secrets.delete("9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d")
```

## `secrets.get`

```http
GET /secrets/by-id/{id}
```

The secret with this id. Throws `NotFoundError` when there is none.

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

**Path parameters**

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

**Response:** [`Secret`](https://docs.maitento.com/reference/types/secret.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/secrets/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const secret = await mt.secrets.get("c0ffee00-1234-4abc-9def-0123456789ab");
```
```python title="Python"
mt.secrets.get("9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d")
```

## `secrets.update`

```http
PUT /secrets/by-id/{id}
```

Renames a secret and, when `value` is given, replaces its value.

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

**Path parameters**

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

**Request body:** [`SecretUpdateRequest`](https://docs.maitento.com/reference/types/secret-update-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes | The secret's name. |
| `value` | `string \| null` |  | A new value, kept exactly as sent. Null or omitted: the stored value is kept. |

**Response:** [`Secret`](https://docs.maitento.com/reference/types/secret.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/secrets/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"..."}'
```
```ts title="TypeScript"
await mt.secrets.update("c0ffee00-1234-4abc-9def-0123456789ab", { name: "orders-api-key", value: process.env.ORDERS_API_KEY_NEW! });
```
```python title="Python"
mt.secrets.update("9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", name="orders-api-key", value=os.environ["ORDERS_API_KEY"])
```

## `secrets.getByName`

```http
GET /secrets/by-name/{name}
```

The secret with this name. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fsecrets%2Fby-name%2F%7Bname%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes |  |

**Response:** [`Secret`](https://docs.maitento.com/reference/types/secret.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/secrets/by-name/<name>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const secret = await mt.secrets.getByName("orders-api-key");
```
```python title="Python"
mt.secrets.get_by_name("orders-api-key")
```