Mason/agent auth

agents/auth/credentials.mdx

@@ -0,0 +1,177 @@
+---
+title: "Credentials"
+---
+
+Credentials enable fully automated authentication. Without credentials, users provide login info via the [Hosted UI](/agents/auth/hosted-ui) or [Programmatic](/agents/auth/programmatic) flow. With credentials saved, Kernel handles login automatically—both the first time and when sessions expire.
+
+## Save credentials during login
+
+Add `save_credential_as` to any invocation. The credentials entered during login are securely stored:
+
+<CodeGroup>
+```typescript TypeScript
+const invocation = await kernel.agents.auth.invocations.create({
+  auth_agent_id: agent.id,
+  save_credential_as: 'my-login',
+});
+```
+
+```python Python
+invocation = await kernel.agents.auth.invocations.create(
+    auth_agent_id=agent.id,
+    save_credential_as="my-login",
+)
+```
+</CodeGroup>
+
+Once saved, the profile stays authenticated automatically. When the session expires, Kernel re-authenticates using the stored credentials—no user interaction needed.
+
+## Pre-store credentials
+
+For fully automated flows where no user is involved, create credentials upfront:
+
+<CodeGroup>
+```typescript TypeScript
+const credential = await kernel.credentials.create({
+  name: 'my-netflix-login',
+  domain: 'netflix.com',
+  values: {
+    email: 'user@netflix.com',
+    password: 'secretpassword123',
+  },
+});
+```
+
+```python Python
+credential = await kernel.credentials.create(
+    name="my-netflix-login",
+    domain="netflix.com",
+    values={
+        "email": "user@netflix.com",
+        "password": "secretpassword123",
+    },
+)
+```
+</CodeGroup>
+
+Then link the credential to an auth agent:
+
+<CodeGroup>
+```typescript TypeScript
+const agent = await kernel.agents.auth.create({
+  domain: 'netflix.com',
+  profile_name: 'my-profile',
+  credential_name: credential.name,
+});
+
+// Start invocation - logs in automatically using stored credentials
+const invocation = await kernel.agents.auth.invocations.create({
+  auth_agent_id: agent.id,
+});
+```
+
+```python Python
+agent = await kernel.agents.auth.create(
+    domain="netflix.com",
+    profile_name="my-profile",
+    credential_name=credential.name,
+)
+
+# Start invocation - logs in automatically using stored credentials
+invocation = await kernel.agents.auth.invocations.create(
+    auth_agent_id=agent.id,
+)
+```
+</CodeGroup>
+
+### 2FA with TOTP
+
+For sites with authenticator app 2FA, include `totp_secret` to fully automate login:
+
+<CodeGroup>
+```typescript TypeScript
+const credential = await kernel.credentials.create({
+  name: 'my-login',
+  domain: 'github.com',
+  values: {
+    username: 'my-username',
+    password: 'my-password',
+  },
+  totp_secret: 'JBSWY3DPEHPK3PXP',  // From authenticator app setup
+});
+```
+
+```python Python
+credential = await kernel.credentials.create(
+    name="my-login",
+    domain="github.com",
+    values={
+        "username": "my-username",
+        "password": "my-password",
+    },
+    totp_secret="JBSWY3DPEHPK3PXP",  # From authenticator app setup
+)
+```
+</CodeGroup>
+
+### SSO / OAuth
+
+For sites with "Sign in with Google/GitHub/Microsoft", set `sso_provider` and include the OAuth provider in `allowed_domains`:
+
+<CodeGroup>
+```typescript TypeScript
+const credential = await kernel.credentials.create({
+  name: 'my-google-login',
+  domain: 'accounts.google.com',
+  sso_provider: 'google',
+  values: {
+    email: 'user@gmail.com',
+    password: 'password',
+  },
+});
+
+const agent = await kernel.agents.auth.create({
+  domain: 'target-site.com',
+  profile_name: 'my-profile',
+  credential_name: credential.name,
+  allowed_domains: ['accounts.google.com', 'google.com'],
+});
+```
+
+```python Python
+credential = await kernel.credentials.create(
+    name="my-google-login",
+    domain="accounts.google.com",
+    sso_provider="google",
+    values={
+        "email": "user@gmail.com",
+        "password": "password",
+    },
+)
+
+agent = await kernel.agents.auth.create(
+    domain="target-site.com",
+    profile_name="my-profile",
+    credential_name=credential.name,
+    allowed_domains=["accounts.google.com", "google.com"],
+)
+```
+</CodeGroup>
+
+The workflow automatically clicks the matching SSO button and completes OAuth.
+
+## Security
+
+| Feature | Description |
+|---------|-------------|
+| **Encrypted at rest** | Values encrypted using per-organization keys |
+| **Write-only** | Values cannot be retrieved via API after creation |
+| **Never logged** | Values are never written to logs |
+| **Never shared** | Values are never passed to LLMs |
+| **Isolated execution** | Authentication runs in isolated browser environments |
+
+## Notes
+
+- The `values` object is flexible—store whatever fields the login form needs (`email`, `username`, `company_id`, etc.)
+- Deleting a credential unlinks it from associated auth agents; they'll no longer auto-authenticate
+- One credential per account—create separate credentials for different user accounts

agents/auth/early-preview.mdx

@@ -0,0 +1,56 @@
+---
+title: "Early Preview"
+description: "Agent Auth early preview documentation"
+---
+
+<Info>
+Agent Auth is now documented in the main docs. See the pages below for current documentation.
+</Info>
+
+<CardGroup cols={2}>
+  <Card title="Overview" icon="book" href="/agents/auth/overview">
+    Introduction to Agent Auth and key concepts
+  </Card>
+  <Card title="Hosted UI" icon="browser" href="/agents/auth/hosted-ui">
+    Redirect users to complete login themselves
+  </Card>
+  <Card title="Programmatic" icon="code" href="/agents/auth/programmatic">
+    Build custom auth flows with full control
+  </Card>
+  <Card title="Credentials" icon="key" href="/agents/auth/credentials">
+    Store credentials for automated re-auth
+  </Card>
+</CardGroup>
+
+## Early Preview SDK Installation
+
+For early preview testers, install the preview SDK:
+
+**TypeScript/Node.js:**
+
+```json
+{
+  "dependencies": {
+    "@onkernel/sdk": "https://pkg.stainless.com/s/kernel-typescript/3f4eb01bb73f679828e195a74f41214d69c01453/dist.tar.gz"
+  }
+}
+```
+
+**Python (requirements.txt):**
+
+```
+kernel @ https://pkg.stainless.com/s/kernel-python/e941d0fb0a62cb8a1aad2424577c825bd6764df4/kernel-0.24.0-py3-none-any.whl
+```
+
+Or in pyproject.toml:
+
+```toml
+[project]
+dependencies = [
+    "kernel @ https://pkg.stainless.com/s/kernel-python/e941d0fb0a62cb8a1aad2424577c825bd6764df4/kernel-0.24.0-py3-none-any.whl",
+]
+```
+
+## Support
+
+Questions or issues? Reach out to us on Slack!