@primitivedotdev/sdk 0.31.1 → 0.31.2

package/dist/{operations.generated-BOlpIYkQ.js → operations.generated-CDIos4wH.js}

@@ -10,7 +10,7 @@ const openapiDocument = {
 	"info": {
 		"title": "Primitive API",
 		"version": "1.0.0",
-		"description": "The Primitive API lets you manage domains, emails, webhook endpoints,\nfilters, and account settings programmatically.\n\n## Authentication\n\nMost endpoints require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer prim_<your_api_key>\n```\n\nAPI keys are org-scoped. Create and manage them in your dashboard\nunder Settings > API Keys. CLI login and signup endpoints explicitly\ndeclare `security: []`; they do not require an API key because they\nare used to mint one.\n\n## Rate Limiting\n\nThe API enforces a sliding window rate limit of **120 requests per\n60 seconds** per organization. When exceeded, the API returns `429`\nwith a `Retry-After` header indicating how many seconds to wait.\n\n## Pagination\n\nList endpoints use cursor-based pagination. Responses include a\n`meta` object with `total`, `limit`, and `cursor` fields. Pass the\n`cursor` value as a query parameter to fetch the next page. When\n`cursor` is `null`, there are no more results.\n\n## Response Format\n\nAll responses use a consistent envelope:\n\n```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"meta\": { \"total\": 42, \"limit\": 50, \"cursor\": \"...\" }\n}\n```\n\nErrors follow the same pattern:\n\n```json\n{\n  \"success\": false,\n  \"error\": { \"code\": \"not_found\", \"message\": \"Email not found\" }\n}\n```\n\n## Webhook signing\n\nOutbound webhook deliveries (configured via the `endpoints` API)\nare signed so receivers can verify they came from Primitive and\nhave not been tampered with in transit. The signing scheme is\ndeliberately simple so it can be reimplemented in any language\nin a few lines. The Node SDK's `verifyWebhookSignature` helper\nis the reference implementation; the wire details below let you\nwrite a verifier in Python, Go, Ruby, etc. without reading our\nsource.\n\n**Header**: `Primitive-Signature: t=<unix-seconds>,v1=<hex>`\n\nA legacy `MyMX-Signature` header is also sent on every delivery\nwith the same value, retained for back-compatibility with\nintegrations written before the rename. New code should read\n`Primitive-Signature`.\n\n**Signed string**: `${timestamp}.${rawBody}` where `timestamp`\nis the Unix-seconds integer from the `t=` parameter and\n`rawBody` is the exact bytes of the HTTP request body BEFORE\nany JSON decoding. Verify against the raw body, not a\nre-serialized parse, or you will silently mismatch on\ninsignificant whitespace.\n\n**Signature**: HMAC-SHA256 of the signed string, hex-encoded\n(lowercase). Use the account's webhook secret as the HMAC key,\nas a UTF-8 byte sequence.\n\n**Secret**: returned by `GET /account/webhook-secret`. The\nstring looks base64-shaped (e.g. `XNHBBW8VqoBjRfNs1tkZj11jTk...`)\nbut is NOT base64; use it AS-IS as a UTF-8 string for the HMAC\nkey. Base64-decoding before HMAC will silently produce\nmismatched signatures.\n\n**Tolerance**: by convention, reject deliveries whose `t=`\ntimestamp is more than 5 minutes off your wall-clock to defend\nagainst replay attacks. The Node SDK's helper enforces this by\ndefault.\n\n**Verification recipe** (any language):\n\n```\n1. Read the raw HTTP body (do not parse).\n2. Read `Primitive-Signature: t=<ts>,v1=<sig>`.\n3. Reject if abs(now - ts) > 300 seconds.\n4. expected = HMAC_SHA256_hex(secret_utf8, f\"{ts}.{rawBody}\")\n5. Constant-time compare expected to sig. Reject if not equal.\n```\n\nFor Node, use `verifyWebhookSignature` from\n`@primitivedotdev/sdk/webhook` (or the higher-level\n`handleWebhook` helper if you want a one-liner). For other\nlanguages, the recipe above is everything you need.\n\nTest deliveries: `POST /endpoints/{id}/test` triggers a fake\ndelivery to your endpoint URL, signed with your real account\nsecret, so you can confirm verification end-to-end without\nneeding real inbound mail. The test response carries the exact\n`signature` header value sent on the wire so you can compare\nstrings directly.\n",
+		"description": "The Primitive API lets you manage domains, emails, webhook endpoints,\nfilters, and account settings programmatically.\n\n## Authentication\n\nMost endpoints require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer prim_<your_api_key>\n```\n\nAPI keys are org-scoped. Create and manage them in your dashboard\nunder Settings > API Keys. CLI login plus CLI/agent signup endpoints\nexplicitly declare `security: []`; they do not require an API key because\nthey are used to create OAuth CLI sessions.\n\n## Rate Limiting\n\nThe API enforces a sliding window rate limit of **120 requests per\n60 seconds** per organization. When exceeded, the API returns `429`\nwith a `Retry-After` header indicating how many seconds to wait.\n\n## Pagination\n\nList endpoints use cursor-based pagination. Responses include a\n`meta` object with `total`, `limit`, and `cursor` fields. Pass the\n`cursor` value as a query parameter to fetch the next page. When\n`cursor` is `null`, there are no more results.\n\n## Response Format\n\nAll responses use a consistent envelope:\n\n```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"meta\": { \"total\": 42, \"limit\": 50, \"cursor\": \"...\" }\n}\n```\n\nErrors follow the same pattern:\n\n```json\n{\n  \"success\": false,\n  \"error\": { \"code\": \"not_found\", \"message\": \"Email not found\" }\n}\n```\n\n## Webhook signing\n\nOutbound webhook deliveries (configured via the `endpoints` API)\nare signed so receivers can verify they came from Primitive and\nhave not been tampered with in transit. The signing scheme is\ndeliberately simple so it can be reimplemented in any language\nin a few lines. The Node SDK's `verifyWebhookSignature` helper\nis the reference implementation; the wire details below let you\nwrite a verifier in Python, Go, Ruby, etc. without reading our\nsource.\n\n**Header**: `Primitive-Signature: t=<unix-seconds>,v1=<hex>`\n\nA legacy `MyMX-Signature` header is also sent on every delivery\nwith the same value, retained for back-compatibility with\nintegrations written before the rename. New code should read\n`Primitive-Signature`.\n\n**Signed string**: `${timestamp}.${rawBody}` where `timestamp`\nis the Unix-seconds integer from the `t=` parameter and\n`rawBody` is the exact bytes of the HTTP request body BEFORE\nany JSON decoding. Verify against the raw body, not a\nre-serialized parse, or you will silently mismatch on\ninsignificant whitespace.\n\n**Signature**: HMAC-SHA256 of the signed string, hex-encoded\n(lowercase). Use the account's webhook secret as the HMAC key,\nas a UTF-8 byte sequence.\n\n**Secret**: returned by `GET /account/webhook-secret`. The\nstring looks base64-shaped (e.g. `XNHBBW8VqoBjRfNs1tkZj11jTk...`)\nbut is NOT base64; use it AS-IS as a UTF-8 string for the HMAC\nkey. Base64-decoding before HMAC will silently produce\nmismatched signatures.\n\n**Tolerance**: by convention, reject deliveries whose `t=`\ntimestamp is more than 5 minutes off your wall-clock to defend\nagainst replay attacks. The Node SDK's helper enforces this by\ndefault.\n\n**Verification recipe** (any language):\n\n```\n1. Read the raw HTTP body (do not parse).\n2. Read `Primitive-Signature: t=<ts>,v1=<sig>`.\n3. Reject if abs(now - ts) > 300 seconds.\n4. expected = HMAC_SHA256_hex(secret_utf8, f\"{ts}.{rawBody}\")\n5. Constant-time compare expected to sig. Reject if not equal.\n```\n\nFor Node, use `verifyWebhookSignature` from\n`@primitivedotdev/sdk/webhook` (or the higher-level\n`handleWebhook` helper if you want a one-liner). For other\nlanguages, the recipe above is everything you need.\n\nTest deliveries: `POST /endpoints/{id}/test` triggers a fake\ndelivery to your endpoint URL, signed with your real account\nsecret, so you can confirm verification end-to-end without\nneeding real inbound mail. The test response carries the exact\n`signature` header value sent on the wire so you can compare\nstrings directly.\n",
 		"contact": {
 			"name": "Primitive",
 			"url": "https://primitive.dev"
@@ -33,6 +33,10 @@ const openapiDocument = {
 			"name": "CLI",
 			"description": "Browser-assisted CLI authentication"
 		},
+		{
+			"name": "Agent",
+			"description": "Agent signup and authentication"
+		},
 		{
 			"name": "Account",
 			"description": "Manage your account settings, storage, and webhook secret"
@@ -96,7 +100,7 @@ const openapiDocument = {
 		"/cli/login/poll": { "post": {
 			"operationId": "pollCliLogin",
 			"summary": "Poll CLI browser login",
-			"description": "Polls a CLI login session until the browser approval either succeeds,\nis denied, expires, or is polled too quickly. The API key is generated\nonly after approval and is returned exactly once.\n",
+			"description": "Polls a CLI login session until the browser approval either succeeds,\nis denied, expires, or is polled too quickly. The OAuth token set is\ncreated only after approval and is returned exactly once.\n",
 			"tags": ["CLI"],
 			"security": [],
 			"requestBody": {
@@ -105,7 +109,7 @@ const openapiDocument = {
 			},
 			"responses": {
 				"200": {
-					"description": "CLI login approved and API key created",
+					"description": "CLI login approved and OAuth token set created",
 					"headers": { "Cache-Control": {
 						"schema": { "type": "string" },
 						"description": "Always `no-store`"
@@ -246,8 +250,8 @@ const openapiDocument = {
 		} },
 		"/cli/signup/verify": { "post": {
 			"operationId": "verifyCliSignup",
-			"summary": "Verify CLI signup and create API key",
-			"description": "Verifies the email code for a CLI signup session, creates the account,\nredeems the reserved signup code, mints an org-scoped CLI API key, and\nreturns the raw key exactly once. This endpoint does not require an API key.\n",
+			"summary": "Verify CLI signup and create OAuth session",
+			"description": "Verifies the email code for a CLI signup session, creates the account,\nredeems the reserved signup code, creates an org-scoped OAuth CLI\nsession, and returns the token set exactly once. This endpoint does not\nrequire an API key.\n",
 			"tags": ["CLI"],
 			"security": [],
 			"requestBody": {
@@ -256,7 +260,7 @@ const openapiDocument = {
 			},
 			"responses": {
 				"200": {
-					"description": "CLI signup verified and API key created",
+					"description": "CLI signup verified and OAuth token set created",
 					"headers": { "Cache-Control": {
 						"schema": { "type": "string" },
 						"description": "Always `no-store`"
@@ -273,10 +277,106 @@ const openapiDocument = {
 				"429": { "$ref": "#/components/responses/RateLimited" }
 			}
 		} },
+		"/agent/signup/start": { "post": {
+			"operationId": "startAgentSignup",
+			"summary": "Start agent account signup",
+			"description": "Starts an agent-native signup session. The API validates the signup code,\ncreates a pending signup session, sends an email verification code, and\nreturns an opaque signup token used by the resend and verify steps. This\nendpoint does not require an API key.\n",
+			"tags": ["Agent"],
+			"security": [],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartAgentSignupInput" } } }
+			},
+			"responses": {
+				"201": {
+					"description": "Agent signup session created and verification email sent",
+					"headers": { "Cache-Control": {
+						"schema": { "type": "string" },
+						"description": "Always `no-store`"
+					} },
+					"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+						"type": "object",
+						"properties": { "data": { "$ref": "#/components/schemas/AgentSignupStartResult" } }
+					}] } } }
+				},
+				"400": { "$ref": "#/components/responses/ValidationError" },
+				"429": { "$ref": "#/components/responses/RateLimited" }
+			}
+		} },
+		"/agent/signup/resend": { "post": {
+			"operationId": "resendAgentSignupVerification",
+			"summary": "Resend agent signup verification code",
+			"description": "Sends a new email verification code for a pending agent signup session.\nThis endpoint does not require an API key.\n",
+			"tags": ["Agent"],
+			"security": [],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendAgentSignupVerificationInput" } } }
+			},
+			"responses": {
+				"200": {
+					"description": "Verification email resent",
+					"headers": { "Cache-Control": {
+						"schema": { "type": "string" },
+						"description": "Always `no-store`"
+					} },
+					"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+						"type": "object",
+						"properties": { "data": { "$ref": "#/components/schemas/AgentSignupResendResult" } }
+					}] } } }
+				},
+				"400": {
+					"description": "Invalid token or expired token",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
+				},
+				"429": {
+					"description": "Global rate limit exceeded or resend requested too quickly",
+					"headers": { "Retry-After": {
+						"schema": { "type": "integer" },
+						"description": "Seconds to wait before retrying"
+					} },
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
+				}
+			}
+		} },
+		"/agent/signup/verify": { "post": {
+			"operationId": "verifyAgentSignup",
+			"summary": "Verify agent signup and create OAuth tokens",
+			"description": "Verifies the email code for an agent signup session, creates the account\nwhen needed, redeems the reserved signup code, mints an org-scoped OAuth\nsession for CLI authentication, and returns the raw tokens exactly once.\nFor existing users, the optional `org_id` selects which accessible\nworkspace should receive the new session.\n",
+			"tags": ["Agent"],
+			"security": [],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyAgentSignupInput" } } }
+			},
+			"responses": {
+				"200": {
+					"description": "Agent signup verified and OAuth tokens created",
+					"headers": { "Cache-Control": {
+						"schema": { "type": "string" },
+						"description": "Always `no-store`"
+					} },
+					"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+						"type": "object",
+						"properties": { "data": { "$ref": "#/components/schemas/AgentSignupVerifyResult" } }
+					}] } } }
+				},
+				"400": {
+					"description": "Invalid request, invalid verification code, expired token, invalid signup code, or account creation failure",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
+				},
+				"403": { "$ref": "#/components/responses/Forbidden" },
+				"409": {
+					"description": "Existing account is not in a usable workspace state",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
+				},
+				"429": { "$ref": "#/components/responses/RateLimited" }
+			}
+		} },
 		"/cli/logout": { "post": {
 			"operationId": "cliLogout",
-			"summary": "Revoke the current CLI API key",
-			"description": "Revokes the API key used to authenticate the request. CLI clients use\nthis endpoint during `primitive logout` before removing local credentials.\n",
+			"summary": "Revoke the current CLI OAuth session",
+			"description": "Revokes the OAuth grant used to authenticate the request. API-key\nauthenticated legacy logout requests succeed without deleting server API\nkeys so old local CLI state can be cleared safely.\n",
 			"tags": ["CLI"],
 			"requestBody": {
 				"required": false,
@@ -284,7 +384,7 @@ const openapiDocument = {
 			},
 			"responses": {
 				"200": {
-					"description": "CLI API key revoked",
+					"description": "CLI logout completed",
 					"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
 						"type": "object",
 						"properties": { "data": { "$ref": "#/components/schemas/CliLogoutResult" } }
@@ -2012,7 +2112,14 @@ const openapiDocument = {
 									"slow_down",
 									"access_denied",
 									"expired_token",
-									"invalid_device_code"
+									"invalid_device_code",
+									"invalid_signup_code",
+									"invalid_signup_token",
+									"invalid_verification_code",
+									"email_delivery_failed",
+									"clerk_signup_failed",
+									"no_orgs_for_user",
+									"org_not_accessible"
 								]
 							},
 							"message": { "type": "string" },
@@ -2196,13 +2303,42 @@ const openapiDocument = {
 				"properties": {
 					"api_key": {
 						"type": "string",
-						"description": "Newly-created API key for CLI authentication"
+						"description": "Legacy alias for access_token. New CLI builds should persist access_token and refresh_token."
 					},
 					"key_id": {
+						"type": "string",
+						"format": "uuid",
+						"description": "Legacy alias for oauth_grant_id"
+					},
+					"key_prefix": {
+						"type": "string",
+						"description": "Legacy display prefix derived from access_token"
+					},
+					"access_token": {
+						"type": "string",
+						"description": "OAuth access token for CLI API authentication"
+					},
+					"refresh_token": {
+						"type": "string",
+						"description": "OAuth refresh token used by the CLI to renew access"
+					},
+					"token_type": {
+						"type": "string",
+						"enum": ["Bearer"]
+					},
+					"expires_in": {
+						"type": "integer",
+						"description": "Seconds until access_token expires"
+					},
+					"auth_method": {
+						"type": "string",
+						"enum": ["oauth"]
+					},
+					"oauth_grant_id": {
 						"type": "string",
 						"format": "uuid"
 					},
-					"key_prefix": { "type": "string" },
+					"oauth_client_id": { "type": "string" },
 					"org_id": {
 						"type": "string",
 						"format": "uuid"
@@ -2213,6 +2349,13 @@ const openapiDocument = {
 					"api_key",
 					"key_id",
 					"key_prefix",
+					"access_token",
+					"refresh_token",
+					"token_type",
+					"expires_in",
+					"auth_method",
+					"oauth_grant_id",
+					"oauth_client_id",
 					"org_id",
 					"org_name"
 				]
@@ -2240,7 +2383,7 @@ const openapiDocument = {
 						"type": "string",
 						"minLength": 1,
 						"maxLength": 80,
-						"description": "Human-readable device name used for the created CLI API key"
+						"description": "Human-readable device name used for the created CLI OAuth grant"
 					},
 					"metadata": {
 						"type": "object",
@@ -2341,36 +2484,273 @@ const openapiDocument = {
 						"maxLength": 1024
 					}
 				},
+				"required": ["signup_token", "verification_code"]
+			},
+			"CliSignupVerifyResult": {
+				"type": "object",
+				"properties": {
+					"api_key": {
+						"type": "string",
+						"description": "Legacy alias for access_token. New CLI builds should persist access_token and refresh_token."
+					},
+					"key_id": {
+						"type": "string",
+						"format": "uuid",
+						"description": "Legacy alias for oauth_grant_id"
+					},
+					"key_prefix": {
+						"type": "string",
+						"description": "Legacy display prefix derived from access_token"
+					},
+					"access_token": {
+						"type": "string",
+						"description": "OAuth access token for CLI API authentication"
+					},
+					"refresh_token": {
+						"type": "string",
+						"description": "OAuth refresh token used by the CLI to renew access"
+					},
+					"token_type": {
+						"type": "string",
+						"enum": ["Bearer"]
+					},
+					"expires_in": {
+						"type": "integer",
+						"description": "Seconds until access_token expires"
+					},
+					"auth_method": {
+						"type": "string",
+						"enum": ["oauth"]
+					},
+					"oauth_grant_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"oauth_client_id": { "type": "string" },
+					"org_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"org_name": { "type": ["string", "null"] }
+				},
+				"required": [
+					"api_key",
+					"key_id",
+					"key_prefix",
+					"access_token",
+					"refresh_token",
+					"token_type",
+					"expires_in",
+					"auth_method",
+					"oauth_grant_id",
+					"oauth_client_id",
+					"org_id",
+					"org_name"
+				]
+			},
+			"StartAgentSignupInput": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"email": {
+						"type": "string",
+						"format": "email",
+						"maxLength": 254
+					},
+					"signup_code": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 128
+					},
+					"terms_accepted": {
+						"type": "boolean",
+						"const": true,
+						"description": "Must be true to confirm acceptance of Primitive's Terms of Service and Privacy Policy"
+					},
+					"device_name": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 80,
+						"description": "Human-readable device name used for the created agent OAuth session"
+					},
+					"metadata": {
+						"type": "object",
+						"additionalProperties": true,
+						"description": "Optional client metadata stored with the signup session; serialized JSON must be 2048 bytes or fewer"
+					}
+				},
+				"required": [
+					"email",
+					"signup_code",
+					"terms_accepted"
+				]
+			},
+			"AgentSignupStartResult": {
+				"type": "object",
+				"properties": {
+					"signup_token": {
+						"type": "string",
+						"description": "Opaque token used to verify or resend the pending agent signup"
+					},
+					"email": {
+						"type": "string",
+						"format": "email"
+					},
+					"expires_in": {
+						"type": "integer",
+						"description": "Seconds until the pending signup expires"
+					},
+					"resend_after": {
+						"type": "integer",
+						"description": "Minimum seconds before requesting another verification email"
+					},
+					"verification_code_length": {
+						"type": "integer",
+						"description": "Number of digits in the emailed verification code"
+					}
+				},
 				"required": [
 					"signup_token",
-					"verification_code",
-					"password"
+					"email",
+					"expires_in",
+					"resend_after",
+					"verification_code_length"
 				]
 			},
-			"CliSignupVerifyResult": {
+			"ResendAgentSignupVerificationInput": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": { "signup_token": {
+					"type": "string",
+					"minLength": 1
+				} },
+				"required": ["signup_token"]
+			},
+			"AgentSignupResendResult": {
+				"type": "object",
+				"properties": {
+					"email": {
+						"type": "string",
+						"format": "email"
+					},
+					"expires_in": {
+						"type": "integer",
+						"description": "Seconds until the pending signup expires"
+					},
+					"resend_after": {
+						"type": "integer",
+						"description": "Minimum seconds before requesting another verification email"
+					},
+					"verification_code_length": {
+						"type": "integer",
+						"description": "Number of digits in the emailed verification code"
+					}
+				},
+				"required": [
+					"email",
+					"expires_in",
+					"resend_after",
+					"verification_code_length"
+				]
+			},
+			"VerifyAgentSignupInput": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"signup_token": {
+						"type": "string",
+						"minLength": 1
+					},
+					"verification_code": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 32
+					},
+					"org_id": {
+						"type": "string",
+						"format": "uuid",
+						"description": "Optional workspace id to target when the verified email already belongs to multiple workspaces"
+					}
+				},
+				"required": ["signup_token", "verification_code"]
+			},
+			"AgentOrgRef": {
+				"type": "object",
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"name": { "type": ["string", "null"] }
+				},
+				"required": ["id", "name"]
+			},
+			"AgentSignupVerifyResult": {
 				"type": "object",
 				"properties": {
 					"api_key": {
 						"type": "string",
-						"description": "Newly-created API key for CLI authentication"
+						"description": "Legacy alias for access_token. New CLI builds should persist access_token and refresh_token."
+					},
+					"key_id": {
+						"type": "string",
+						"format": "uuid",
+						"description": "Legacy alias for oauth_grant_id"
+					},
+					"key_prefix": {
+						"type": "string",
+						"description": "Legacy display prefix derived from access_token"
+					},
+					"access_token": {
+						"type": "string",
+						"description": "OAuth access token for CLI API authentication"
+					},
+					"refresh_token": {
+						"type": "string",
+						"description": "OAuth refresh token used by the CLI to renew access"
+					},
+					"token_type": {
+						"type": "string",
+						"enum": ["Bearer"]
 					},
-					"key_id": {
+					"expires_in": {
+						"type": "integer",
+						"description": "Seconds until access_token expires"
+					},
+					"auth_method": {
+						"type": "string",
+						"enum": ["oauth"]
+					},
+					"oauth_grant_id": {
 						"type": "string",
 						"format": "uuid"
 					},
-					"key_prefix": { "type": "string" },
+					"oauth_client_id": { "type": "string" },
 					"org_id": {
 						"type": "string",
 						"format": "uuid"
 					},
-					"org_name": { "type": ["string", "null"] }
+					"org_name": { "type": ["string", "null"] },
+					"orgs": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/AgentOrgRef" },
+						"description": "Workspaces available to the verified email. The minted session targets `org_id`."
+					}
 				},
 				"required": [
 					"api_key",
 					"key_id",
 					"key_prefix",
+					"access_token",
+					"refresh_token",
+					"token_type",
+					"expires_in",
+					"auth_method",
+					"oauth_grant_id",
+					"oauth_client_id",
 					"org_id",
-					"org_name"
+					"org_name",
+					"orgs"
 				]
 			},
 			"CliLogoutInput": {
@@ -2379,7 +2759,7 @@ const openapiDocument = {
 				"properties": { "key_id": {
 					"type": "string",
 					"format": "uuid",
-					"description": "Optional key id guard; when provided it must match the authenticated API key"
+					"description": "Optional id guard; when provided it must match the authenticated OAuth grant id or API key id"
 				} }
 			},
 			"CliLogoutResult": {
@@ -2387,14 +2767,20 @@ const openapiDocument = {
 				"properties": {
 					"revoked": {
 						"type": "boolean",
-						"const": true
+						"description": "True when an OAuth grant was revoked. False for API-key-authenticated legacy logout, which only clears local CLI state."
 					},
 					"key_id": {
 						"type": "string",
-						"format": "uuid"
+						"format": "uuid",
+						"description": "API key id for API-key-authenticated legacy logout"
+					},
+					"oauth_grant_id": {
+						"type": "string",
+						"format": "uuid",
+						"description": "OAuth grant id revoked by OAuth-authenticated logout"
 					}
 				},
-				"required": ["revoked", "key_id"]
+				"required": ["revoked"]
 			},
 			"Account": {
 				"type": "object",
@@ -4598,11 +4984,263 @@ const operationManifest = [
 		"tag": "Account",
 		"tagCommand": "account"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": true,
+		"command": "resend-agent-signup-verification",
+		"description": "Sends a new email verification code for a pending agent signup session.\nThis endpoint does not require an API key.\n",
+		"hasJsonBody": true,
+		"method": "POST",
+		"operationId": "resendAgentSignupVerification",
+		"path": "/agent/signup/resend",
+		"pathParams": [],
+		"queryParams": [],
+		"requestSchema": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": { "signup_token": {
+				"type": "string",
+				"minLength": 1
+			} },
+			"required": ["signup_token"]
+		},
+		"responseSchema": {
+			"type": "object",
+			"properties": {
+				"email": {
+					"type": "string",
+					"format": "email"
+				},
+				"expires_in": {
+					"type": "integer",
+					"description": "Seconds until the pending signup expires"
+				},
+				"resend_after": {
+					"type": "integer",
+					"description": "Minimum seconds before requesting another verification email"
+				},
+				"verification_code_length": {
+					"type": "integer",
+					"description": "Number of digits in the emailed verification code"
+				}
+			},
+			"required": [
+				"email",
+				"expires_in",
+				"resend_after",
+				"verification_code_length"
+			]
+		},
+		"sdkName": "resendAgentSignupVerification",
+		"summary": "Resend agent signup verification code",
+		"tag": "Agent",
+		"tagCommand": "agent"
+	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": true,
+		"command": "start-agent-signup",
+		"description": "Starts an agent-native signup session. The API validates the signup code,\ncreates a pending signup session, sends an email verification code, and\nreturns an opaque signup token used by the resend and verify steps. This\nendpoint does not require an API key.\n",
+		"hasJsonBody": true,
+		"method": "POST",
+		"operationId": "startAgentSignup",
+		"path": "/agent/signup/start",
+		"pathParams": [],
+		"queryParams": [],
+		"requestSchema": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"email": {
+					"type": "string",
+					"format": "email",
+					"maxLength": 254
+				},
+				"signup_code": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 128
+				},
+				"terms_accepted": {
+					"type": "boolean",
+					"const": true,
+					"description": "Must be true to confirm acceptance of Primitive's Terms of Service and Privacy Policy"
+				},
+				"device_name": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 80,
+					"description": "Human-readable device name used for the created agent OAuth session"
+				},
+				"metadata": {
+					"type": "object",
+					"additionalProperties": true,
+					"description": "Optional client metadata stored with the signup session; serialized JSON must be 2048 bytes or fewer"
+				}
+			},
+			"required": [
+				"email",
+				"signup_code",
+				"terms_accepted"
+			]
+		},
+		"responseSchema": {
+			"type": "object",
+			"properties": {
+				"signup_token": {
+					"type": "string",
+					"description": "Opaque token used to verify or resend the pending agent signup"
+				},
+				"email": {
+					"type": "string",
+					"format": "email"
+				},
+				"expires_in": {
+					"type": "integer",
+					"description": "Seconds until the pending signup expires"
+				},
+				"resend_after": {
+					"type": "integer",
+					"description": "Minimum seconds before requesting another verification email"
+				},
+				"verification_code_length": {
+					"type": "integer",
+					"description": "Number of digits in the emailed verification code"
+				}
+			},
+			"required": [
+				"signup_token",
+				"email",
+				"expires_in",
+				"resend_after",
+				"verification_code_length"
+			]
+		},
+		"sdkName": "startAgentSignup",
+		"summary": "Start agent account signup",
+		"tag": "Agent",
+		"tagCommand": "agent"
+	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": true,
+		"command": "verify-agent-signup",
+		"description": "Verifies the email code for an agent signup session, creates the account\nwhen needed, redeems the reserved signup code, mints an org-scoped OAuth\nsession for CLI authentication, and returns the raw tokens exactly once.\nFor existing users, the optional `org_id` selects which accessible\nworkspace should receive the new session.\n",
+		"hasJsonBody": true,
+		"method": "POST",
+		"operationId": "verifyAgentSignup",
+		"path": "/agent/signup/verify",
+		"pathParams": [],
+		"queryParams": [],
+		"requestSchema": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"signup_token": {
+					"type": "string",
+					"minLength": 1
+				},
+				"verification_code": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 32
+				},
+				"org_id": {
+					"type": "string",
+					"format": "uuid",
+					"description": "Optional workspace id to target when the verified email already belongs to multiple workspaces"
+				}
+			},
+			"required": ["signup_token", "verification_code"]
+		},
+		"responseSchema": {
+			"type": "object",
+			"properties": {
+				"api_key": {
+					"type": "string",
+					"description": "Legacy alias for access_token. New CLI builds should persist access_token and refresh_token."
+				},
+				"key_id": {
+					"type": "string",
+					"format": "uuid",
+					"description": "Legacy alias for oauth_grant_id"
+				},
+				"key_prefix": {
+					"type": "string",
+					"description": "Legacy display prefix derived from access_token"
+				},
+				"access_token": {
+					"type": "string",
+					"description": "OAuth access token for CLI API authentication"
+				},
+				"refresh_token": {
+					"type": "string",
+					"description": "OAuth refresh token used by the CLI to renew access"
+				},
+				"token_type": {
+					"type": "string",
+					"enum": ["Bearer"]
+				},
+				"expires_in": {
+					"type": "integer",
+					"description": "Seconds until access_token expires"
+				},
+				"auth_method": {
+					"type": "string",
+					"enum": ["oauth"]
+				},
+				"oauth_grant_id": {
+					"type": "string",
+					"format": "uuid"
+				},
+				"oauth_client_id": { "type": "string" },
+				"org_id": {
+					"type": "string",
+					"format": "uuid"
+				},
+				"org_name": { "type": ["string", "null"] },
+				"orgs": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"name": { "type": ["string", "null"] }
+						},
+						"required": ["id", "name"]
+					},
+					"description": "Workspaces available to the verified email. The minted session targets `org_id`."
+				}
+			},
+			"required": [
+				"api_key",
+				"key_id",
+				"key_prefix",
+				"access_token",
+				"refresh_token",
+				"token_type",
+				"expires_in",
+				"auth_method",
+				"oauth_grant_id",
+				"oauth_client_id",
+				"org_id",
+				"org_name",
+				"orgs"
+			]
+		},
+		"sdkName": "verifyAgentSignup",
+		"summary": "Verify agent signup and create OAuth tokens",
+		"tag": "Agent",
+		"tagCommand": "agent"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": false,
 		"command": "cli-logout",
-		"description": "Revokes the API key used to authenticate the request. CLI clients use\nthis endpoint during `primitive logout` before removing local credentials.\n",
+		"description": "Revokes the OAuth grant used to authenticate the request. API-key\nauthenticated legacy logout requests succeed without deleting server API\nkeys so old local CLI state can be cleared safely.\n",
 		"hasJsonBody": true,
 		"method": "POST",
 		"operationId": "cliLogout",
@@ -4615,7 +5253,7 @@ const operationManifest = [
 			"properties": { "key_id": {
 				"type": "string",
 				"format": "uuid",
-				"description": "Optional key id guard; when provided it must match the authenticated API key"
+				"description": "Optional id guard; when provided it must match the authenticated OAuth grant id or API key id"
 			} }
 		},
 		"responseSchema": {
@@ -4623,17 +5261,23 @@ const operationManifest = [
 			"properties": {
 				"revoked": {
 					"type": "boolean",
-					"const": true
+					"description": "True when an OAuth grant was revoked. False for API-key-authenticated legacy logout, which only clears local CLI state."
 				},
 				"key_id": {
 					"type": "string",
-					"format": "uuid"
+					"format": "uuid",
+					"description": "API key id for API-key-authenticated legacy logout"
+				},
+				"oauth_grant_id": {
+					"type": "string",
+					"format": "uuid",
+					"description": "OAuth grant id revoked by OAuth-authenticated logout"
 				}
 			},
-			"required": ["revoked", "key_id"]
+			"required": ["revoked"]
 		},
 		"sdkName": "cliLogout",
-		"summary": "Revoke the current CLI API key",
+		"summary": "Revoke the current CLI OAuth session",
 		"tag": "CLI",
 		"tagCommand": "cli"
 	},
@@ -4641,7 +5285,7 @@ const operationManifest = [
 		"binaryResponse": false,
 		"bodyRequired": true,
 		"command": "poll-cli-login",
-		"description": "Polls a CLI login session until the browser approval either succeeds,\nis denied, expires, or is polled too quickly. The API key is generated\nonly after approval and is returned exactly once.\n",
+		"description": "Polls a CLI login session until the browser approval either succeeds,\nis denied, expires, or is polled too quickly. The OAuth token set is\ncreated only after approval and is returned exactly once.\n",
 		"hasJsonBody": true,
 		"method": "POST",
 		"operationId": "pollCliLogin",
@@ -4662,13 +5306,42 @@ const operationManifest = [
 			"properties": {
 				"api_key": {
 					"type": "string",
-					"description": "Newly-created API key for CLI authentication"
+					"description": "Legacy alias for access_token. New CLI builds should persist access_token and refresh_token."
 				},
 				"key_id": {
+					"type": "string",
+					"format": "uuid",
+					"description": "Legacy alias for oauth_grant_id"
+				},
+				"key_prefix": {
+					"type": "string",
+					"description": "Legacy display prefix derived from access_token"
+				},
+				"access_token": {
+					"type": "string",
+					"description": "OAuth access token for CLI API authentication"
+				},
+				"refresh_token": {
+					"type": "string",
+					"description": "OAuth refresh token used by the CLI to renew access"
+				},
+				"token_type": {
+					"type": "string",
+					"enum": ["Bearer"]
+				},
+				"expires_in": {
+					"type": "integer",
+					"description": "Seconds until access_token expires"
+				},
+				"auth_method": {
+					"type": "string",
+					"enum": ["oauth"]
+				},
+				"oauth_grant_id": {
 					"type": "string",
 					"format": "uuid"
 				},
-				"key_prefix": { "type": "string" },
+				"oauth_client_id": { "type": "string" },
 				"org_id": {
 					"type": "string",
 					"format": "uuid"
@@ -4679,6 +5352,13 @@ const operationManifest = [
 				"api_key",
 				"key_id",
 				"key_prefix",
+				"access_token",
+				"refresh_token",
+				"token_type",
+				"expires_in",
+				"auth_method",
+				"oauth_grant_id",
+				"oauth_client_id",
 				"org_id",
 				"org_name"
 			]
@@ -4845,7 +5525,7 @@ const operationManifest = [
 					"type": "string",
 					"minLength": 1,
 					"maxLength": 80,
-					"description": "Human-readable device name used for the created CLI API key"
+					"description": "Human-readable device name used for the created CLI OAuth grant"
 				},
 				"metadata": {
 					"type": "object",
@@ -4900,7 +5580,7 @@ const operationManifest = [
 		"binaryResponse": false,
 		"bodyRequired": true,
 		"command": "verify-cli-signup",
-		"description": "Verifies the email code for a CLI signup session, creates the account,\nredeems the reserved signup code, mints an org-scoped CLI API key, and\nreturns the raw key exactly once. This endpoint does not require an API key.\n",
+		"description": "Verifies the email code for a CLI signup session, creates the account,\nredeems the reserved signup code, creates an org-scoped OAuth CLI\nsession, and returns the token set exactly once. This endpoint does not\nrequire an API key.\n",
 		"hasJsonBody": true,
 		"method": "POST",
 		"operationId": "verifyCliSignup",
@@ -4926,24 +5606,49 @@ const operationManifest = [
 					"maxLength": 1024
 				}
 			},
-			"required": [
-				"signup_token",
-				"verification_code",
-				"password"
-			]
+			"required": ["signup_token", "verification_code"]
 		},
 		"responseSchema": {
 			"type": "object",
 			"properties": {
 				"api_key": {
 					"type": "string",
-					"description": "Newly-created API key for CLI authentication"
+					"description": "Legacy alias for access_token. New CLI builds should persist access_token and refresh_token."
 				},
 				"key_id": {
+					"type": "string",
+					"format": "uuid",
+					"description": "Legacy alias for oauth_grant_id"
+				},
+				"key_prefix": {
+					"type": "string",
+					"description": "Legacy display prefix derived from access_token"
+				},
+				"access_token": {
+					"type": "string",
+					"description": "OAuth access token for CLI API authentication"
+				},
+				"refresh_token": {
+					"type": "string",
+					"description": "OAuth refresh token used by the CLI to renew access"
+				},
+				"token_type": {
+					"type": "string",
+					"enum": ["Bearer"]
+				},
+				"expires_in": {
+					"type": "integer",
+					"description": "Seconds until access_token expires"
+				},
+				"auth_method": {
+					"type": "string",
+					"enum": ["oauth"]
+				},
+				"oauth_grant_id": {
 					"type": "string",
 					"format": "uuid"
 				},
-				"key_prefix": { "type": "string" },
+				"oauth_client_id": { "type": "string" },
 				"org_id": {
 					"type": "string",
 					"format": "uuid"
@@ -4954,12 +5659,19 @@ const operationManifest = [
 				"api_key",
 				"key_id",
 				"key_prefix",
+				"access_token",
+				"refresh_token",
+				"token_type",
+				"expires_in",
+				"auth_method",
+				"oauth_grant_id",
+				"oauth_client_id",
 				"org_id",
 				"org_name"
 			]
 		},
 		"sdkName": "verifyCliSignup",
-		"summary": "Verify CLI signup and create API key",
+		"summary": "Verify CLI signup and create OAuth session",
 		"tag": "CLI",
 		"tagCommand": "cli"
 	},