> Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

---
title: Credentials
"og:image": "https://libretto.sh/docs/og/libretto-cloud-api/credentials.png"
---

> Use the credentials API to store, update, list, read, and delete tenant-scoped credentials.

All routes on this page require `x-api-key`.

### Using stored credentials in jobs

The credentials API stores encrypted tenant-scoped key/value credentials. A
workflow must declare the credential names it needs; hosted execution injects
only those names from Libretto Cloud's credential store into workflow params
under `credentials`. Local non-production `libretto run` injects matching
`LIBRETTO_CLOUD_` variables from `.env` into the same field.
For example, `LIBRETTO_CLOUD_OPENAI_API_KEY` resolves to
`input.credentials.openai_api_key`.

```typescript
import { workflow } from "libretto";

export default workflow("portal-login", {
  credentials: ["username", "password"],
  async handler(ctx, input) {
    const credentials = input.credentials;

    await ctx.page.fill('[name="username"]', credentials.username);
    await ctx.page.fill('[name="password"]', credentials.password);
  },
});
```

### POST `/v1/credentials/create`

Store a new credential value.

Request fields:

* `name`: credential name
* `value`: string value to encrypt and store

Response fields:

* `success`
* `credential_id`
* `message`

### POST `/v1/credentials/list`

List stored credentials.

Response fields:

* `credentials`

Each credential entry includes:

* `credential_id`
* `name`
* `created_at`
* `updated_at`

### POST `/v1/credentials/get`

Read a stored credential by name.

Request fields:

* `name`: credential name

Response fields:

* `id`
* `value`

### POST `/v1/credentials/update`

Update a credential by id.

Request fields:

* `id`: credential id
* `value`: optional replacement string value
* `name`: optional new name

Response fields:

* `success`
* `message`

### POST `/v1/credentials/delete`

Delete a credential by id.

Request fields:

* `id`: credential id

Response fields:

* `success`
* `message`

Deletion is blocked while queued or running jobs still reference the credential.

<CardGroup cols={3}>
  <Card title="Webhooks" icon="lucide:webhook" href="/libretto-cloud-api/webhooks">
    Configure tenant-level job result webhooks.
  </Card>

  <Card title="Jobs and Logs" icon="terminal" href="/libretto-cloud-api/jobs-and-logs">
    Run workflows that may use stored credentials.
  </Card>

  <Card title="Schedules" icon="clock" href="/libretto-cloud-api/schedules">
    Schedule recurring workflow runs.
  </Card>
</CardGroup>