SOP 007: Credentials API

Fresh

Field	Value
SOP ID	SOP-007
Version	1.0
Status	Active (Beta)
Source	Steel Credentials API

Overview

Securely store and inject login credentials into browser sessions without exposing them to agents or the page. Uses enterprise-grade envelope encryption (AES-256-GCM).

Prerequisites

• Steel account with API key
• Target site login URL and credentials

Credential Injection Flow

Procedure

Step 1: Create Credentials

await client.credentials.create({
  origin: "https://app.example.com",
  value: {
    username: "test@example.com",
    password: "password123"
  }
});

Step 2: With TOTP Support

await client.credentials.create({
  origin: "https://app.example.com",
  value: {
    username: "test@example.com",
    password: "password123",
    totpSecret: "JBSWY3DPEHPK3PXP"
  }
});

Step 3: Create Session with Credential Injection

const session = await client.sessions.create({
  namespace: "default",
  credentials: {}  // Empty object = use defaults
});

// Custom options
const session = await client.sessions.create({
  namespace: "default",
  credentials: {
    autoSubmit: true,    // Auto-submit login form
    blurFields: true,    // Blur fields to prevent agent reading
    exactOrigin: true    // Only inject on exact origin match
  }
});

Step 4: Navigate and Wait

await page.goto("https://app.example.com/login");
await page.waitForSelector("form");
await page.waitForTimeout(2000);  // Wait for injection
await page.waitForSelector(".dashboard");  // Confirm login

Namespaces

Use namespaces to manage multiple credentials for the same origin:

// Create Fred's credentials
await client.credentials.create({
  namespace: "example:fred",
  origin: "https://app.example.com",
  value: { username: "fred@example.com", password: "hunter2" }
});

// Create Jane's credentials
await client.credentials.create({
  namespace: "example:jane",
  origin: "https://app.example.com",
  value: { username: "jane@example.com", password: "letmein" }
});

// Use Fred's credentials
const session = await client.sessions.create({
  namespace: "example:fred",
  credentials: {}
});

Security Architecture

• Envelope encryption: Each credential gets its own AES-256-GCM key
• KMS-backed: Data keys encrypted by org-specific KMS master key
• AAD binding: Ciphertext bound to org ID and origin (prevents replay attacks)
• Field blurring: Inputs blurred after fill to prevent vision agents reading PII
• No logging: Credentials never logged or stored in plaintext

Verification Checklist

• [ ] Credential created with correct origin
• [ ] Session created with matching namespace
• [ ] Credential injection occurs within ~2 seconds
• [ ] Login form auto-submitted (if autoSubmit: true)
• [ ] Agent cannot read credential values from DOM

Troubleshooting

Issue	Solution
Credentials not injecting	Check origin matches exactly, verify namespace
Wrong credentials used	Ensure namespace matches between credential and session
TOTP not filling	Verify totpSecret is the base32-encoded secret
Login fails after fill	Disable autoSubmit and debug manually

See Also

• SOP 005: Reuse Auth Context
• SOP 008: Browser Profiles
• Workflow: Authenticated Scraping