---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/logins/credentials
markdown_url: https://steel.dev/docs/logins/credentials.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Credentials
description: Store logins in Steel and let a session fill them into sign-in forms, so your code and your agent never need the password.
summary: Store logins in Steel and let a session fill them into sign-in forms, so your code and your agent never need the password.
type: how-to
stage: beta
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/logins/browser-state.md
related:
  - https://steel.dev/docs/logins/browser-state.md
  - https://steel.dev/docs/logins/stay-signed-in.md
  - https://steel.dev/docs/logins/profiles.md
  - https://steel.dev/docs/logins/session-context.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Credentials

A credential is a login that Steel stores for a website: a username and password and, if the site asks for one, a one-time password secret. A session that you create with the `credentials` option fills the stored values into the site's sign-in form. Your code and your agent never need the password, and Steel never returns it. By default, [snapshots](https://steel.dev/docs/control/snapshots-and-refs#snapshots) mask the filled username and password, but code that reads the page, such as a Playwright script, can still read a filled field. Use credentials when a session must sign in on its own each time. [Browser state](https://steel.dev/docs/logins/browser-state) compares them with a profile and session context, which start a session already signed in.

> **Note**
>
> Credentials are in Beta. They can change. See [Release stages](https://steel.dev/docs/platform/release-stages).

## Before you begin

Put your Steel API key in the `STEEL_API_KEY` environment variable. Then install the Steel SDK and Playwright.

**TypeScript**

```sh
npm install steel-sdk playwright
```

**Python**

```sh
python3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwright
```

**Go**

```sh
go mod init store-credential
go get github.com/steel-dev/sdk/go
```

**Rust**

```sh
cargo new store-credential
cd store-credential
cargo add steel-rs
cargo add tokio --features macros,rt-multi-thread
```

In Go and Rust, install only the SDK, as the [Go](https://steel.dev/docs/reference/sdks/go#install) and [Rust](https://steel.dev/docs/reference/sdks/rust#install) SDK pages show. The code that drives the browser uses Playwright, so it is in TypeScript and Python only.

## Store a credential

Call `client.credentials.create` with the site's `origin` and the login in `value`. The origin is the sign-in page's scheme, host and port, such as `https://app.example.com`. Steel encrypts the value and stores it in a project and a namespace, so you store it once and use it in any session of that project and namespace.

This program stores a login for Steel's practice site, and prints what Steel stored. It reads the login from the `SITE_USERNAME` and `SITE_PASSWORD` environment variables. Set them to the test login that the site's [sign-in page](https://steel.dev/practice/login) shows.

**TypeScript**

```ts file=store-credential.mts
import Steel from "steel-sdk";

const client = new Steel();

const credential = await client.credentials.create({
  origin: "https://steel.dev",
  value: {
    username: process.env.SITE_USERNAME!,
    password: process.env.SITE_PASSWORD!,
  },
});
console.log(JSON.stringify(credential, null, 2));
```

**Python**

```python file=store_credential.py
import json
import os

from steel import Steel

client = Steel()

credential = client.credentials.create(
    origin="https://steel.dev",
    value={
        "username": os.environ["SITE_USERNAME"],
        "password": os.environ["SITE_PASSWORD"],
    },
)
print(json.dumps(credential.to_dict(mode="json"), indent=2))
```

**Go**

```go file=main.go
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"os"

	"github.com/steel-dev/sdk/go"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	client := steel.NewClient()

	credential, err := client.Credentials.New(ctx, steel.CredentialNewParams{
		Origin: steel.F("https://steel.dev"),
		Value: steel.F(map[string]string{
			"username": os.Getenv("SITE_USERNAME"),
			"password": os.Getenv("SITE_PASSWORD"),
		}),
	})
	if err != nil {
		return err
	}
	out, err := json.MarshalIndent(credential, "", "  ")
	if err != nil {
		return err
	}
	fmt.Println(string(out))
	return nil
}
```

**Rust**

```rust file=src/main.rs
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = steel_rs::Client::new();

    let credential = client
        .credentials()
        .create(steel_rs::CredentialCreateParams {
            origin: Some("https://steel.dev".to_owned()),
            ..steel_rs::CredentialCreateParams::new(std::collections::HashMap::from([
                ("username".to_owned(), std::env::var("SITE_USERNAME")?),
                ("password".to_owned(), std::env::var("SITE_PASSWORD")?),
            ]))
        })
        .await?;
    println!("{}", serde_json::to_string_pretty(&credential)?);
    Ok(())
}
```

In Rust, the program also needs `cargo add serde_json`. Run the program:

**TypeScript**

```sh
npx tsx store-credential.mts
```

**Python**

```sh
python store_credential.py
```

**Go**

```sh
go run .
```

**Rust**

```sh
cargo run
```

The response has no `value`. The API never returns the stored login.

**TypeScript**

```json nocopy
{
  "createdAt": "2026-11-11T12:35:41.405Z",
  "updatedAt": "2026-11-11T12:35:41.405Z",
  "namespace": "default",
  "origin": "https://steel.dev",
  "label": "https://steel.dev"
}
```

**Python**

```json nocopy
{
  "createdAt": "2026-11-11T12:31:49.311Z",
  "updatedAt": "2026-11-11T12:31:49.311Z",
  "label": "https://steel.dev",
  "namespace": "default",
  "origin": "https://steel.dev"
}
```

**Go**

```json nocopy
{
  "createdAt": "2026-11-11T03:03:09.947Z",
  "updatedAt": "2026-11-11T03:03:09.947Z",
  "label": "https://steel.dev",
  "namespace": "default",
  "origin": "https://steel.dev"
}
```

**Rust**

```json nocopy
{
  "createdAt": "2026-11-11T03:03:18.397Z",
  "updatedAt": "2026-11-11T03:03:18.397Z",
  "label": "https://steel.dev",
  "namespace": "default",
  "origin": "https://steel.dev"
}
```

A value can hold these keys:

- `username`: the username or email address. When a value has no `username`, Steel uses the first of `email`, `login` and `identifier` that it has.
- `password`: the password.
- `totpSecret`: the secret of a one-time password app. Steel creates a fresh code when the site asks for one.

[Limits](https://steel.dev/docs/platform/limits#size-limits) gives the largest size of a value.

You can also add a `label` and a `namespace`. Use namespaces to keep separate logins for the same origin, for example one for each of your users. Steel stores one credential for each origin in each namespace. When you leave out `namespace`, Steel uses `default`, which is also the namespace of a session whose request names none. See [Projects and namespaces](https://steel.dev/docs/production/projects-and-namespaces).

## Use credentials in a session

Pass `credentials` when you create the session. An empty object turns on credentials with the default options, which [Session configuration](https://steel.dev/docs/sessions/configuration#credentials) lists. The session uses the credentials in its own namespace. If you stored the credential with a `namespace`, create the session with the same `namespace`.

Steel watches each page for a sign-in form: a `<form>` element with a username, password or one-time password field. It skips a form whose `action`, or whose submit button's `formaction`, goes to another origin. Then it looks for a stored credential whose `origin` is the page's origin, with the same scheme, host and port. If there is none, it looks for a credential stored under the page's host alone, such as `steel.dev`. A subdomain is another origin, so a credential for `https://example.com` does not fill `https://app.example.com`. When Steel finds a credential, it fills the form's username, password and one-time password fields and, by default, submits the form.

This program opens the sign-in page and waits for the page that a signed-in user sees.

**TypeScript**

```ts file=use-credentials.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();
const session = await client.sessions.create({ credentials: {} });

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://steel.dev/practice/login");
  await page.waitForURL("https://steel.dev/practice/secure");
  console.log(page.url());
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}
```

**Python**

```python file=use_credentials.py
from playwright.sync_api import sync_playwright
from steel import Steel

client = Steel()
session = client.sessions.create(credentials={})

try:
    with sync_playwright() as playwright:
        browser = playwright.chromium.connect_over_cdp(session.websocket_url)
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://steel.dev/practice/login")
        page.wait_for_url("https://steel.dev/practice/secure")
        print(page.url)
        browser.close()
finally:
    client.sessions.release(session.id)
```

Run the program:

**TypeScript**

```sh
npx tsx use-credentials.mts
```

**Python**

```sh
python use_credentials.py
```

The program prints the URL of the page after the login.

```text nocopy
https://steel.dev/practice/secure
```

Steel fills the form shortly after the page loads. Wait for a sign that the login worked, such as a page or an element that only a signed-in user sees. A filled field does not prove that the site accepted the login.

## Use credentials with a profile

A session can start from a [profile](https://steel.dev/docs/logins/profiles) and use credentials too. It starts signed in, and when the site shows its sign-in form, Steel fills it.

Today, this works only with a profile that a session without `credentials` saved. A session that uses `credentials` and saves a profile, with `persistProfile: true`, keeps the login in the profile. But later sessions that start from that profile cannot fill credentials, and the sign-in form stays empty. So save the profile from a session without `credentials`, and sign in there with your own code or by hand in the [live view](https://steel.dev/docs/observability/live-view). In the sessions that use credentials, leave out `persistProfile`. [Stay signed in across sessions](https://steel.dev/docs/logins/stay-signed-in) shows the steps.

## Limit which sites get credentials

In `credentials`, set `origins` to the list of origins that the session may fill. Steel then fills no other site in this session, even if you stored a credential for it. Use it when an agent browses freely, so that a session for one task cannot fill another task's logins.

**TypeScript**

```ts
const session = await client.sessions.create({
  credentials: { origins: ["https://app.example.com"] },
});
```

**Python**

```python
session = client.sessions.create(
    credentials={"origins": ["https://app.example.com"]},
)
```

**Go**

```go
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	Credentials: steel.F(steel.SessionNewParamsCredentials{
		Origins: steel.F([]string{"https://app.example.com"}),
	}),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        credentials: Some(steel_rs::SessionCreateParamsCredentials {
            origins: Some(vec!["https://app.example.com".to_owned()]),
            ..Default::default()
        }),
        ..Default::default()
    })
    .await?;
```

## Update or delete a credential

Steel finds a credential by its `origin` and `namespace`. To change the stored value, call `client.credentials.update` with the `origin` and the new `value`. For a credential in a namespace other than `default`, add its `namespace`. You can also change the `label`.

**TypeScript**

```ts
await client.credentials.update({
  origin: "https://app.example.com",
  value: {
    username: process.env.SITE_USERNAME!,
    password: process.env.SITE_PASSWORD!,
  },
});
```

**Python**

```python
client.credentials.update(
    origin="https://app.example.com",
    value={
        "username": os.environ["SITE_USERNAME"],
        "password": os.environ["SITE_PASSWORD"],
    },
)
```

**Go**

```go
import "os"

if _, err := client.Credentials.Update(ctx, steel.CredentialUpdateParams{
	Origin: steel.F("https://app.example.com"),
	Value: steel.F(map[string]string{
		"username": os.Getenv("SITE_USERNAME"),
		"password": os.Getenv("SITE_PASSWORD"),
	}),
}); err != nil {
	return err
}
```

**Rust**

```rust
client
    .credentials()
    .update(steel_rs::CredentialUpdateParams {
        origin: Some("https://app.example.com".to_owned()),
        value: Some(std::collections::HashMap::from([
            ("username".to_owned(), std::env::var("SITE_USERNAME")?),
            ("password".to_owned(), std::env::var("SITE_PASSWORD")?),
        ])),
        ..Default::default()
    })
    .await?;
```

To remove a credential, call `client.credentials.delete` with its `origin`. For a credential in a namespace other than `default`, add its `namespace`.

**TypeScript**

```ts
await client.credentials.delete({ origin: "https://app.example.com" });
```

**Python**

```python
client.credentials.delete(origin="https://app.example.com")
```

**Go**

```go
if _, err := client.Credentials.Delete(ctx, steel.CredentialDeleteParams{
	Origin: steel.F("https://app.example.com"),
}); err != nil {
	return err
}
```

**Rust**

```rust
client
    .credentials()
    .delete(steel_rs::CredentialDeleteParams::new(
        "https://app.example.com".to_owned(),
    ))
    .await?;
```

To see what you stored, call `client.credentials.list`. It lists the credentials of one namespace: the `namespace` that you pass, or `default`. You can also filter it by `origin`. It returns the same fields as `create`, without the values.

## Check that it worked

Call `client.credentials.list` (`client.Credentials.List` in Go) with the `origin` `https://steel.dev`. Its `credentials` list has the login that you stored, without its `value`. Then run the program in [Use credentials in a session](https://steel.dev/docs/logins/credentials#use-credentials-in-a-session). It prints `https://steel.dev/practice/secure` only after the site accepts the login that Steel filled in. If `waitForURL` (`wait_for_url` in Python) times out instead, see [The sign-in form stays empty](https://steel.dev/docs/logins/credentials#the-sign-in-form-stays-empty).

## Troubleshooting

### A credential already exists for origin

```json nocopy
{
  "error": "Conflict",
  "message": "A credential already exists for origin 'https://app.example.com' in namespace 'default'. Use the update endpoint to change it, or delete it first to recreate.",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/credentials-api/overview"
}
```

**Cause:** The namespace already holds a credential for this origin.

**Fix:** Call `client.credentials.update` to change the value, or store the new login in another `namespace`.

**Verify:** The call returns the credential with a new `updatedAt`.

### No credential found for origin

```json nocopy
{
  "error": "Not Found",
  "message": "No credential found for origin 'https://app.example.com' in namespace 'default'. Check the origin and namespace, or store a credential for it first.",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/credentials-api/overview"
}
```

**Cause:** An update or delete names an origin and namespace that hold no credential.

**Fix:** Call `client.credentials.list` with the namespace that you stored the credential in, and use the `origin` that it returns. Without a `namespace`, the list has only the credentials in `default`.

**Verify:** The update or delete succeeds.

### The sign-in form stays empty

**Cause:** Steel does not find a credential for the page, or it does not fill the form. It finds no credential when the session has no `credentials` option, when the session's namespace differs from the credential's, when the stored `origin` is neither the page's origin nor its host, or when the origin is not in `origins`. It fills nothing when the session starts from a profile that a session with `credentials` saved. It skips fields that are not inside a `<form>` element, a form inside a shadow root, and a form whose `action`, or whose submit button's `formaction`, goes to another origin.

**Fix:** Create the session with `credentials` and the credential's `namespace`. Compare the sign-in page's scheme, host and port with the stored `origin`. If the session starts from a profile, see [Use credentials with a profile](https://steel.dev/docs/logins/credentials#use-credentials-with-a-profile). Steel cannot fill the fields and forms that it skips, and some sign-in methods, such as passkeys and single sign-on, do not use a username and password. For those, [hand control to a human](https://steel.dev/docs/observability/hand-control-to-a-human).

**Verify:** Open the session's [live view](https://steel.dev/docs/observability/live-view). The fields fill shortly after the page loads.

## Next steps

- [Stay signed in across sessions](https://steel.dev/docs/logins/stay-signed-in): Start each session signed in from a profile, and let credentials sign in again when the login expires.
