# Credential stacks

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

## `credentialStacks.list`

```http
GET /credential-stacks
```

Every credential stack of the tenant.

**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%2Fcredential-stacks).

**Response:** [`CredentialStack`](https://docs.maitento.com/reference/types/credential-stack.md)`[]` (200)

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

## `credentialStacks.create`

```http
POST /credential-stacks
```

Creates a stack and returns it, with its id. Refused with `ValidationError` when the name is taken, an entry names a credential the tenant hasn't got, or the plan's stack limit is reached.

**Who can call it:** Tenant admins only, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fcredential-stacks).

**Request body:** [`CredentialStackRequest`](https://docs.maitento.com/reference/types/credential-stack-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` |  |  |
| `description` | `string \| null` |  |  |
| `entries` | [`CredentialStackEntryInput`](https://docs.maitento.com/reference/types/credential-stack-entry.md#in-a-request)`[]` |  | In the order they're tried. Each names a credential in the same tenant. |

**Response:** [`CredentialStack`](https://docs.maitento.com/reference/types/credential-stack.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/credential-stacks" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"...","description":"...","entries":[]}'
```
```ts title="TypeScript"
const stack = await mt.credentialStacks.create({ name: "production", entries: [{ credentialId: "6f1d2c3b-4a5e-4f60-8b7c-9d0e1f2a3b4c" }, { credentialId: "7a2e3d4c-5b6f-4071-9c8d-0e1f2a3b4c5d", allowedEndpointKinds: ["Foundry"] }] });
```
```python title="Python"
mt.credential_stacks.create(name="production", entries=[{"credentialId": "3e4f5a6b-7c8d-4e9f-a0b1-c2d3e4f5a6b7"}, {"credentialId": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f", "allowedModels": ["gpt-5-mini"]}])
```

## `credentialStacks.delete`

```http
DELETE /credential-stacks/by-id/{id}
```

Deletes a stack. Refused with `ValidationError` while it's the tenant's or a namespace's default.

**Who can call it:** Tenant admins only, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fcredential-stacks%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/credential-stacks/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.credentialStacks.delete("5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f");
```
```python title="Python"
mt.credential_stacks.delete("5a6b7c8d-9e0f-4a1b-8c2d-e3f4a5b6c7d8")
```

## `credentialStacks.get`

```http
GET /credential-stacks/by-id/{id}
```

The stack 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%2Fcredential-stacks%2Fby-id%2F%7Bid%7D).

**Path parameters**

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

**Response:** [`CredentialStack`](https://docs.maitento.com/reference/types/credential-stack.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/credential-stacks/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const stack = await mt.credentialStacks.get("5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f");
```
```python title="Python"
mt.credential_stacks.get("5a6b7c8d-9e0f-4a1b-8c2d-e3f4a5b6c7d8")
```

## `credentialStacks.update`

```http
PUT /credential-stacks/by-id/{id}
```

Replaces a stack's name, description and entries. Runs already going keep the version they started with.

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

**Path parameters**

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

**Request body:** [`CredentialStackRequest`](https://docs.maitento.com/reference/types/credential-stack-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` |  |  |
| `description` | `string \| null` |  |  |
| `entries` | [`CredentialStackEntryInput`](https://docs.maitento.com/reference/types/credential-stack-entry.md#in-a-request)`[]` |  | In the order they're tried. Each names a credential in the same tenant. |

**Response:** [`CredentialStack`](https://docs.maitento.com/reference/types/credential-stack.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/credential-stacks/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"...","description":"...","entries":[]}'
```
```ts title="TypeScript"
await mt.credentialStacks.update("5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f", { name: "production", entries: [{ credentialId: "6f1d2c3b-4a5e-4f60-8b7c-9d0e1f2a3b4c", allowedModels: ["gpt-5"] }, { credentialId: "7a2e3d4c-5b6f-4071-9c8d-0e1f2a3b4c5d", enabled: false }] });
```
```python title="Python"
mt.credential_stacks.update("5a6b7c8d-9e0f-4a1b-8c2d-e3f4a5b6c7d8", name="production", entries=[{"credentialId": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f"}, {"credentialId": "3e4f5a6b-7c8d-4e9f-a0b1-c2d3e4f5a6b7", "enabled": False}])
```

## `credentialStacks.usage`

```http
GET /credential-stacks/by-id/{id}/usage
```

Where the stack is used: whether it's the tenant's default, the namespaces whose default it is, and the knowledge bases that embed with it. While any of these use it, it can't be deleted.

**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%2Fcredential-stacks%2Fby-id%2F%7Bid%7D%2Fusage).

**Path parameters**

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

**Response:** [`CredentialStackUsage`](https://docs.maitento.com/reference/types/credential-stack-usage.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/credential-stacks/by-id/<id>/usage" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const { tenantDefault, namespaces, partitions } = await mt.credentialStacks.usage("5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f");
```
```python title="Python"
mt.credential_stacks.usage("5a6b7c8d-9e0f-4a1b-8c2d-e3f4a5b6c7d8")
```

## `credentialStacks.findByName`

```http
GET /credential-stacks/by-name/{name}
```

The stack with this name (unique in the tenant), or `null`.

**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%2Fcredential-stacks%2Fby-name%2F%7Bname%7D).

**Path parameters**

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

**Response:** [`CredentialStack`](https://docs.maitento.com/reference/types/credential-stack.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/credential-stacks/by-name/<name>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const stack = await mt.credentialStacks.findByName("production"); // null when there's none
```
```python title="Python"
mt.credential_stacks.find_by_name("production")
```

## `credentialStacks.getNamespaceDefault`

```http
GET /namespaces/by-id/{id}/default-credential-stack
```

A namespace's default stack: the one runs of its definitions use when neither their start nor definition names one.

**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%2Fnamespaces%2Fby-id%2F%7Bid%7D%2Fdefault-credential-stack).

**Path parameters**

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

**Response:** [`DefaultCredentialStack`](https://docs.maitento.com/reference/types/default-credential-stack.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/by-id/<id>/default-credential-stack" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const { credentialStackId } = await mt.credentialStacks.getNamespaceDefault("b5f3d1a9-7e6c-4b4a-9a2e-8c0d1f3e5a7b");
```
```python title="Python"
mt.credential_stacks.get_namespace_default("0f1e2d3c-4b5a-4968-8776-655443322110")
```

## `credentialStacks.setNamespaceDefault`

```http
PUT /namespaces/by-id/{id}/default-credential-stack
```

Sets a namespace's default stack, by id; `null` clears it, so the tenant's default applies.

**Who can call it:** Tenant admins only, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fnamespaces%2Fby-id%2F%7Bid%7D%2Fdefault-credential-stack).

**Path parameters**

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

**Request body:** [`DefaultCredentialStackInput`](https://docs.maitento.com/reference/types/default-credential-stack.md#in-a-request)

| Field | Type | Required | Description |
|---|---|---|---|
| `credentialStackId` | `uuid \| null` |  |  |

**Response:** [`DefaultCredentialStack`](https://docs.maitento.com/reference/types/default-credential-stack.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/by-id/<id>/default-credential-stack" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"credentialStackId":"..."}'
```
```ts title="TypeScript"
await mt.credentialStacks.setNamespaceDefault("b5f3d1a9-7e6c-4b4a-9a2e-8c0d1f3e5a7b", "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f");
```
```python title="Python"
mt.credential_stacks.set_namespace_default("0f1e2d3c-4b5a-4968-8776-655443322110", "5a6b7c8d-9e0f-4a1b-8c2d-e3f4a5b6c7d8")
```

## `credentialStacks.getTenantDefault`

```http
GET /tenants/self/default-credential-stack
```

The tenant's default stack: the one runs use when neither their start, definition nor namespace names one.

**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%2Ftenants%2Fself%2Fdefault-credential-stack).

**Response:** [`DefaultCredentialStack`](https://docs.maitento.com/reference/types/default-credential-stack.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/tenants/self/default-credential-stack" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const { credentialStackId } = await mt.credentialStacks.getTenantDefault();
```
```python title="Python"
mt.credential_stacks.get_tenant_default()
```

## `credentialStacks.setTenantDefault`

```http
PUT /tenants/self/default-credential-stack
```

Sets the tenant's default stack, by id; `null` clears it.

**Who can call it:** Tenant admins only, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Ftenants%2Fself%2Fdefault-credential-stack).

**Request body:** [`DefaultCredentialStackInput`](https://docs.maitento.com/reference/types/default-credential-stack.md#in-a-request)

| Field | Type | Required | Description |
|---|---|---|---|
| `credentialStackId` | `uuid \| null` |  |  |

**Response:** [`DefaultCredentialStack`](https://docs.maitento.com/reference/types/default-credential-stack.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/tenants/self/default-credential-stack" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"credentialStackId":"..."}'
```
```ts title="TypeScript"
await mt.credentialStacks.setTenantDefault("5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f"); // null clears it
```
```python title="Python"
mt.credential_stacks.set_tenant_default("5a6b7c8d-9e0f-4a1b-8c2d-e3f4a5b6c7d8")
```