# Credentials

Credentials are named, encrypted secrets your workflow nodes use to authenticate against external services. You store them once, then reference them by name from any node.

## How they're stored

Each workspace gets its own credential store. Credentials are encrypted at rest and only decrypted at execution time — the secret value is never sent to the model.

Secrets are decrypted **only at node execution time** and injected into the outgoing HTTP request, MCP call, or function tool. They are **never serialized into the LLM prompt** and are not visible in node configs or run logs.

## Supported providers

| Provider | Use for | Required fields |
|----------|---------|-----------------|
| `http_bearer` | Any API using `Authorization: Bearer <token>` | Secret |
| `http_apikey` | APIs using an API key header (e.g. `X-API-Key`) | Secret, header name in metadata |
| `http_basic` | HTTP Basic authentication | Password or token; username is configured on the node |
| `gmail` | Gmail API (send + read) via OAuth | Use the **Connect Gmail** button — tokens are stored and auto-refreshed for you |
| `notion` | Notion API (integration token) | Integration token |
| `github_pat` | GitHub API and source control | Fine-grained PAT or OAuth token |
| `smtp` | Sending email through your own SMTP server (Send Email node) | Host, port, username, From address; password as the secret |
| `imap` | Reading mail through an IMAP server | Host, port, SSL, username, password |
| `agent_builder_mail` | Sending email through the shared platform mailbox | None — server-side configuration, no secret to paste |
| `postgres_dsn` | Database Query against PostgreSQL | Host, port, database, username, password, SSL mode |
| `mysql_dsn` | Database Query against MySQL | Host, port, database, username, password |
| `custom` | Opaque secret consumed by your own Function tool | Secret |

## Create a credential

1. Click **Credentials** in the left sidebar.
2. Click **+ Add credential** — or **Connect Gmail** to create a `gmail` credential through the OAuth popup instead of pasting tokens.
3. Fill in:

| Field | Notes |
|-------|-------|
| Name | Human-readable, e.g. `prod-stripe` |
| Provider | Pick from the list above |
| Provider-specific fields | The form changes with the selected provider: database connection fields, API-key header, SMTP/IMAP settings, or token fields |
| Secret | Token, API key, or password (write-only) |
| SMTP fields | `smtp` only: host, port, STARTTLS, username, From address |
| Refresh token | Gmail only, enables auto-refresh |
| Advanced metadata JSON | Optional escape hatch for custom provider metadata; normal setup does not require editing JSON |

4. Save. The credential row appears in the table with a **Test** button that performs a live auth check (you'll be asked for a URL when testing HTTP credentials; SMTP credentials test the connection and login without sending mail).

> You can also connect Gmail **inline from a node**: the Send Email node's Mailbox field has its own Connect Gmail button that creates and auto-selects the credential.

```json
{
  "name": "prod-stripe",
  "provider": "http_bearer",
  "secret_value": "sk_live_...",
  "metadata": null
}
```

## Use a credential in a node

Open any node that talks to an external service (e.g. **HTTP Request**, **Function tool**, **MCP**, **Gmail trigger**). In the config panel you'll see a **Credential** dropdown listing every credential whose provider matches that node. Pick one — that's it.

```yaml
http_request:
  method: POST
  url: https://api.stripe.com/v1/charges
  credential: prod-stripe   # injected as Authorization: Bearer ...
  body: { amount: 1000, currency: "usd" }
```

## Rotating and deleting

- Editing a credential overwrites the stored secret. Existing nodes keep working immediately on the next run.
- Deleting a credential is permanent. Any node still referencing it will fail the next run with an auth error — search by name before deleting.

## Credential audit

Credential governance uses the audit endpoint `GET /api/v1/credentials/{public_id}/audit` to review sensitive lifecycle events for one credential.

Audited actions include:

- `credential.create` — credential record created.
- `credential.update` — name, provider metadata, expiry, or other non-secret fields changed.
- `credential.rotate` — secret or refresh token replaced.
- `credential.share` — credential shared with a team.
- `credential.revoke_share` — team access removed.
- `credential.test` — live provider check requested.
- `credential.delete` — credential removed.

Access is limited to the credential owner, workspace/team admins, and members with the `credential_admin` role for the active workspace. Audit rows store metadata only: actor, timestamp, action, target credential id/name/provider, team/workspace context, and redacted change summaries. Secret values, refresh tokens, OAuth tokens, API keys, plaintext headers, and decrypted vault references must never be written to the audit trail.

For SaaS governance, use this audit trail to answer who created, rotated, shared, tested, revoked, or deleted production credentials, and to prove that access changes were reviewed without exposing the underlying secret.

## Security guarantees

- Secrets are write-only via the API; `GET` never returns the plaintext.
- The frontend never sees decrypted secrets.
- LLM prompts and tool arguments are scrubbed of any value loaded from a credential.
- Credentials are scoped to your workspace and decrypted only at execution time — never exposed to the model.

---

*Source: https://agentbuilder.systalink.sn/docs/credentials — human documentation.*
*Other language: [/docs-md/fr/credentials.md](/docs-md/fr/credentials.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*