@workos/openapi-spec 0.74.0 → 0.76.0

package/dist/open-api-spec.yaml

@@ -975,6 +975,139 @@ paths:
       tags:
         - agents.blueprints.tokens
       x-feature-flag: agent-blueprints-public-api
+  /agents/blueprints/{agent_blueprint_id}/tokens/validate:
+    post:
+      description: >-
+        Validates an agent access token: verifies its signature against the
+        environment, that it was minted under this blueprint, and that the
+        backing session is live (not revoked or expired, and — for delegated
+        sessions — that the delegating user session has not ended). Returns the
+        token claims and session metadata when valid; invalid tokens are
+        reported as errors with stable codes.
+      operationId: AgentBlueprintsTokenController_validateToken
+      parameters:
+        - name: agent_blueprint_id
+          required: true
+          in: path
+          description: The unique ID of the agent blueprint.
+          schema:
+            type: string
+            example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                agent_access_token:
+                  type: string
+                  minLength: 1
+                  description: The agent access token (a JWT) to validate.
+                  example: eyJhbGciOiJSUzI1NiIsImtpZCI6...
+              required:
+                - agent_access_token
+              description: The agent access token to validate.
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentTokenValidation'
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: object
+                    properties:
+                      code:
+                        type: string
+                        description: The error code identifying the type of error.
+                        example: invalid_request
+                        const: invalid_request
+                      message:
+                        type: string
+                        description: A human-readable description of the error.
+                        example: Request could not be processed.
+                    required:
+                      - code
+                      - message
+                  - type: object
+                    properties:
+                      code:
+                        type: string
+                        description: The error code identifying the type of error.
+                        example: invalid_agent_access_token
+                        const: invalid_agent_access_token
+                      message:
+                        type: string
+                        description: A human-readable description of the error.
+                        example: Request could not be processed.
+                    required:
+                      - code
+                      - message
+                  - type: object
+                    properties:
+                      code:
+                        type: string
+                        description: The error code identifying the type of error.
+                        example: session_revoked
+                        const: session_revoked
+                      message:
+                        type: string
+                        description: A human-readable description of the error.
+                        example: Request could not be processed.
+                    required:
+                      - code
+                      - message
+                  - type: object
+                    properties:
+                      code:
+                        type: string
+                        description: The error code identifying the type of error.
+                        example: session_expired
+                        const: session_expired
+                      message:
+                        type: string
+                        description: A human-readable description of the error.
+                        example: Request could not be processed.
+                    required:
+                      - code
+                      - message
+                  - type: object
+                    properties:
+                      code:
+                        type: string
+                        description: The error code identifying the type of error.
+                        example: user_session_ended
+                        const: user_session_ended
+                      message:
+                        type: string
+                        description: A human-readable description of the error.
+                        example: Request could not be processed.
+                    required:
+                      - code
+                      - message
+        '404':
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    description: A human-readable description of the error.
+                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
+                required:
+                  - message
+      summary: Validate an agent token
+      tags:
+        - agents.blueprints.tokens
+      x-feature-flag: agent-blueprints-public-api
   /agents/claims/attempts:
     patch:
       description: >-
@@ -15794,6 +15927,53 @@ paths:
                     - code
                     - pending_authentication_token
                     - authentication_challenge_id
+                - type: object
+                  properties:
+                    client_id:
+                      type: string
+                      description: The client ID of the application.
+                      example: client_01HXYZ123456789ABCDEFGHIJ
+                    client_secret:
+                      type: string
+                      description: The client secret of the application.
+                      example: sk_test_....
+                    grant_type:
+                      type: string
+                      const: urn:workos:oauth:grant-type:email-completion
+                    email_completion_token:
+                      type: string
+                      description: The token from the `email_completion_required` response.
+                      example: JZ8kQ2mR5vT7wX1yA3bC6dE9f
+                    email:
+                      type: string
+                      description: >-
+                        The email address the user supplied for a profile the
+                        identity provider left without one.
+                      example: marcelina@example.com
+                    ip_address:
+                      type: string
+                      description: The IP address of the user's request.
+                      example: 203.0.113.42
+                    device_id:
+                      type: string
+                      description: A unique identifier for the device.
+                      example: device_01HXYZ123456789ABCDEFGHIJ
+                    user_agent:
+                      type: string
+                      description: The user agent string from the user's browser.
+                      example: Mozilla/5.0
+                    signals_id:
+                      type: string
+                      description: >-
+                        An optional Radar signals ID to correlate client-side
+                        signals with this authentication attempt.
+                      example: 01JBS0GN92GC2RJQS4X9DBPQ2A
+                  required:
+                    - client_id
+                    - client_secret
+                    - grant_type
+                    - email_completion_token
+                    - email
                 - type: object
                   properties:
                     client_id:
@@ -16550,6 +16730,27 @@ paths:
                     required:
                       - code
                       - message
+                  - type: object
+                    properties:
+                      code:
+                        type: string
+                        description: The error code identifying the type of error.
+                        example: email_completion_required
+                        const: email_completion_required
+                      message:
+                        type: string
+                        description: A human-readable description of the error.
+                        example: Request could not be processed.
+                      email_completion_token:
+                        type: string
+                        description: >-
+                          Pass this to the `email-completion` grant, with the
+                          address the user supplies, to finish authenticating.
+                        example: JZ8kQ2mR5vT7wX1yA3bC6dE9f
+                    required:
+                      - code
+                      - message
+                      - email_completion_token
                   - type: object
                     properties:
                       code:
@@ -28233,6 +28434,63 @@ components:
         - new_instance
         - agent_instance_session_id
         - permissions
+    AgentTokenValidation:
+      type: object
+      properties:
+        valid:
+          type: boolean
+          description: >-
+            Always `true`: an invalid token is reported as an error with a
+            stable code, never as a `200`.
+          const: true
+        agent_instance_id:
+          type: string
+          description: The agent instance the token was minted for.
+          example: agent_01EHWNCE74X7JSDV0X3SZ3KJNY
+        agent_instance_session_id:
+          type: string
+          description: The agent instance session backing the token.
+          example: agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY
+        organization_id:
+          type: string
+          description: The organization the agent acts within.
+          example: org_01EHWNCE74X7JSDV0X3SZ3KJNY
+        permissions:
+          type: array
+          items:
+            type: string
+          description: The effective permission slugs carried by the token.
+          example:
+            - crm:read
+        intent:
+          type:
+            - string
+            - 'null'
+          description: >-
+            The caller-supplied context echoed into the token at mint time, or
+            `null` when none was given.
+          example: renew-contract-123
+        acting_user_id:
+          type:
+            - string
+            - 'null'
+          description: >-
+            The delegating user carried in the `act.sub` claim of the token, or
+            `null` for autonomous sessions.
+          example: userland_user_01EHWNCE74X7JSDV0X3SZ3KJNY
+        session_expires_at:
+          type: string
+          description: When the backing agent instance session expires.
+          example: '2024-01-01T00:00:00.000Z'
+      required:
+        - valid
+        - agent_instance_id
+        - agent_instance_session_id
+        - organization_id
+        - permissions
+        - intent
+        - acting_user_id
+        - session_expires_at
     AgentInstanceSession:
       type: object
       properties:

package/dist/policy.mjs

@@ -35,6 +35,7 @@ const operationHints = {
 		urlBuilder: true
 	},
 	"POST /portal/generate_link": { name: "generate_link" },
+	"POST /agents/blueprints/{agent_blueprint_id}/tokens/validate": { name: "validate_blueprint_token" },
 	"GET /organizations/{organizationId}/feature-flags": { name: "list_organization_feature_flags" },
 	"GET /user_management/users/{userId}/feature-flags": { name: "list_user_feature_flags" },
 	"GET /organizations/{organization_id}/authorized_applications": { name: "list_authorized_applications" },

package/dist/services.mjs

@@ -62,6 +62,11 @@ const serviceEndpoints = {
 			"path": "/agents/blueprints/{agent_blueprint_id}/tokens",
 			"name": "create_blueprint_token"
 		},
+		{
+			"method": "POST",
+			"path": "/agents/blueprints/{agent_blueprint_id}/tokens/validate",
+			"name": "validate_blueprint_token"
+		},
 		{
 			"method": "PATCH",
 			"path": "/agents/claims/attempts",

package/dist/types.d.ts

@@ -76,6 +76,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/agents/blueprints/{agent_blueprint_id}/tokens/validate": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Validate an agent token
+         * @description Validates an agent access token: verifies its signature against the environment, that it was minted under this blueprint, and that the backing session is live (not revoked or expired, and — for delegated sessions — that the delegating user session has not ended). Returns the token claims and session metadata when valid; invalid tokens are reported as errors with stable codes.
+         */
+        post: operations["AgentBlueprintsTokenController_validateToken"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/agents/claims/attempts": {
         parameters: {
             query?: never;
@@ -6648,6 +6668,50 @@ export interface components {
              */
             permissions: string[];
         };
+        AgentTokenValidation: {
+            /**
+             * @description Always `true`: an invalid token is reported as an error with a stable code, never as a `200`.
+             * @constant
+             */
+            valid: true;
+            /**
+             * @description The agent instance the token was minted for.
+             * @example agent_01EHWNCE74X7JSDV0X3SZ3KJNY
+             */
+            agent_instance_id: string;
+            /**
+             * @description The agent instance session backing the token.
+             * @example agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY
+             */
+            agent_instance_session_id: string;
+            /**
+             * @description The organization the agent acts within.
+             * @example org_01EHWNCE74X7JSDV0X3SZ3KJNY
+             */
+            organization_id: string;
+            /**
+             * @description The effective permission slugs carried by the token.
+             * @example [
+             *       "crm:read"
+             *     ]
+             */
+            permissions: string[];
+            /**
+             * @description The caller-supplied context echoed into the token at mint time, or `null` when none was given.
+             * @example renew-contract-123
+             */
+            intent: string | null;
+            /**
+             * @description The delegating user carried in the `act.sub` claim of the token, or `null` for autonomous sessions.
+             * @example userland_user_01EHWNCE74X7JSDV0X3SZ3KJNY
+             */
+            acting_user_id: string | null;
+            /**
+             * @description When the backing agent instance session expires.
+             * @example 2024-01-01T00:00:00.000Z
+             */
+            session_expires_at: string;
+        };
         AgentInstanceSession: {
             /**
              * @description Distinguishes the agent instance session object.
@@ -20058,6 +20122,123 @@ export interface operations {
             };
         };
     };
+    AgentBlueprintsTokenController_validateToken: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The unique ID of the agent blueprint. */
+                agent_blueprint_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /**
+                     * @description The agent access token (a JWT) to validate.
+                     * @example eyJhbGciOiJSUzI1NiIsImtpZCI6...
+                     */
+                    agent_access_token: string;
+                };
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AgentTokenValidation"];
+                };
+            };
+            /** @description Bad Request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /**
+                         * @description The error code identifying the type of error.
+                         * @example invalid_request
+                         * @constant
+                         */
+                        code: "invalid_request";
+                        /**
+                         * @description A human-readable description of the error.
+                         * @example Request could not be processed.
+                         */
+                        message: string;
+                    } | {
+                        /**
+                         * @description The error code identifying the type of error.
+                         * @example invalid_agent_access_token
+                         * @constant
+                         */
+                        code: "invalid_agent_access_token";
+                        /**
+                         * @description A human-readable description of the error.
+                         * @example Request could not be processed.
+                         */
+                        message: string;
+                    } | {
+                        /**
+                         * @description The error code identifying the type of error.
+                         * @example session_revoked
+                         * @constant
+                         */
+                        code: "session_revoked";
+                        /**
+                         * @description A human-readable description of the error.
+                         * @example Request could not be processed.
+                         */
+                        message: string;
+                    } | {
+                        /**
+                         * @description The error code identifying the type of error.
+                         * @example session_expired
+                         * @constant
+                         */
+                        code: "session_expired";
+                        /**
+                         * @description A human-readable description of the error.
+                         * @example Request could not be processed.
+                         */
+                        message: string;
+                    } | {
+                        /**
+                         * @description The error code identifying the type of error.
+                         * @example user_session_ended
+                         * @constant
+                         */
+                        code: "user_session_ended";
+                        /**
+                         * @description A human-readable description of the error.
+                         * @example Request could not be processed.
+                         */
+                        message: string;
+                    };
+                };
+            };
+            /** @description Not Found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /**
+                         * @description A human-readable description of the error.
+                         * @example Organization not found: 'org_01EHQMYV6MBK39QC5PZXHY59C3'.
+                         */
+                        message: string;
+                    };
+                };
+            };
+        };
+    };
     AgentAdminController_linkClaimAttemptToExternalUser: {
         parameters: {
             query?: never;
@@ -33308,6 +33489,49 @@ export interface operations {
                      * @example Mozilla/5.0
                      */
                     user_agent?: string;
+                } | {
+                    /**
+                     * @description The client ID of the application.
+                     * @example client_01HXYZ123456789ABCDEFGHIJ
+                     */
+                    client_id: string;
+                    /**
+                     * @description The client secret of the application.
+                     * @example sk_test_....
+                     */
+                    client_secret: string;
+                    /** @constant */
+                    grant_type: "urn:workos:oauth:grant-type:email-completion";
+                    /**
+                     * @description The token from the `email_completion_required` response.
+                     * @example JZ8kQ2mR5vT7wX1yA3bC6dE9f
+                     */
+                    email_completion_token: string;
+                    /**
+                     * @description The email address the user supplied for a profile the identity provider left without one.
+                     * @example marcelina@example.com
+                     */
+                    email: string;
+                    /**
+                     * @description The IP address of the user's request.
+                     * @example 203.0.113.42
+                     */
+                    ip_address?: string;
+                    /**
+                     * @description A unique identifier for the device.
+                     * @example device_01HXYZ123456789ABCDEFGHIJ
+                     */
+                    device_id?: string;
+                    /**
+                     * @description The user agent string from the user's browser.
+                     * @example Mozilla/5.0
+                     */
+                    user_agent?: string;
+                    /**
+                     * @description An optional Radar signals ID to correlate client-side signals with this authentication attempt.
+                     * @example 01JBS0GN92GC2RJQS4X9DBPQ2A
+                     */
+                    signals_id?: string;
                 } | {
                     /**
                      * @description The client ID of the application.
@@ -33953,6 +34177,23 @@ export interface operations {
                          * @example Request could not be processed.
                          */
                         message: string;
+                    } | {
+                        /**
+                         * @description The error code identifying the type of error.
+                         * @example email_completion_required
+                         * @constant
+                         */
+                        code: "email_completion_required";
+                        /**
+                         * @description A human-readable description of the error.
+                         * @example Request could not be processed.
+                         */
+                        message: string;
+                        /**
+                         * @description Pass this to the `email-completion` grant, with the address the user supplies, to finish authenticating.
+                         * @example JZ8kQ2mR5vT7wX1yA3bC6dE9f
+                         */
+                        email_completion_token: string;
                     } | {
                         /**
                          * @description The error code identifying the type of error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workos/openapi-spec",
-  "version": "0.74.0",
+  "version": "0.76.0",
   "type": "module",
   "description": "WorkOS OpenAPI specification, TypeScript types, and SDK resolution policy",
   "license": "MIT",