Credentials
Beta
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 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 compares them with a profile and session context, which start a session already signed in.
Before you begin
Put your Steel API key in the STEEL_API_KEY environment variable. Then install the Steel SDK and Playwright.
npm install steel-sdk playwrightpython3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwrightgo mod init store-credential
go get github.com/steel-dev/sdk/gocargo new store-credential
cd store-credential
cargo add steel-rs
cargo add tokio --features macros,rt-multi-threadIn Go and Rust, install only the SDK, as the Go and Rust 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 shows.
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));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))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
}#[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:
npx tsx store-credential.mtspython store_credential.pygo run .cargo runThe response has no value. The API never returns the stored login.
{
"createdAt": "2026-11-11T12:35:41.405Z",
"updatedAt": "2026-11-11T12:35:41.405Z",
"namespace": "default",
"origin": "https://steel.dev",
"label": "https://steel.dev"
}{
"createdAt": "2026-11-11T12:31:49.311Z",
"updatedAt": "2026-11-11T12:31:49.311Z",
"label": "https://steel.dev",
"namespace": "default",
"origin": "https://steel.dev"
}{
"createdAt": "2026-11-11T03:03:09.947Z",
"updatedAt": "2026-11-11T03:03:09.947Z",
"label": "https://steel.dev",
"namespace": "default",
"origin": "https://steel.dev"
}{
"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 nousername, Steel uses the first ofemail,loginandidentifierthat 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 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.
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 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.
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);
}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:
npx tsx use-credentials.mtspython use_credentials.pyThe program prints the URL of the page after the login.
https://steel.dev/practice/secureSteel 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 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. In the sessions that use credentials, leave out persistProfile. Stay signed in across sessions 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.
const session = await client.sessions.create({
credentials: { origins: ["https://app.example.com"] },
});session = client.sessions.create(
credentials={"origins": ["https://app.example.com"]},
)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
}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.
await client.credentials.update({
origin: "https://app.example.com",
value: {
username: process.env.SITE_USERNAME!,
password: process.env.SITE_PASSWORD!,
},
});client.credentials.update(
origin="https://app.example.com",
value={
"username": os.environ["SITE_USERNAME"],
"password": os.environ["SITE_PASSWORD"],
},
)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
}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.
await client.credentials.delete({ origin: "https://app.example.com" });client.credentials.delete(origin="https://app.example.com")if _, err := client.Credentials.Delete(ctx, steel.CredentialDeleteParams{
Origin: steel.F("https://app.example.com"),
}); err != nil {
return err
}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. 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.
Troubleshooting
A credential already exists for origin
{
"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
{
"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. 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.
Verify: Open the session's live view. The fields fill shortly after the page loads.
Next steps
- Stay signed in across sessions: Start each session signed in from a profile, and let credentials sign in again when the login expires.