Move AuthorizationRequired from TAIP-15 to TAIP-4 as standard authorization message

pelle · claude · pelle · commit fd1095d1ba7b · 2025-08-03T18:27:59.000+02:00
- Add AuthorizationRequired message specification to TAIP-4 as core authorization protocol - Include optional 'from' field to specify party type (customer, principal, originator) required to open URL - Update TypeScript interface with enhanced documentation and TAIP-4 reference - Document AuthorizationRequired in messages.md as part of authorization flow - Update TAIP-15 to reference TAIP-4 for complete AuthorizationRequired specification - Add comprehensive test case example and update action list in TAIP-4 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/TAIPs/taip-15.md b/TAIPs/taip-15.md
@@ -5,7 +5,7 @@ status: Review
 type: Standard
 author: Pelle Braendgaard <pelle@notabene.id>
 created: 2024-03-21
-updated: 2025-06-23
+updated: 2025-08-03
 description: Establishes a protocol for creating secure, authorized connections between TAP agents with predefined transaction constraints and OAuth-style authorization flows. Enables persistent B2B integrations with transaction limits, purpose restrictions, and user control mechanisms for ongoing business relationships while maintaining robust risk management.
 requires: [2, 4, 6, 9, 13]
 ---
@@ -70,12 +70,15 @@ A message sent by an agent requesting connection to another agent:
 
 ### AuthorizationRequired Message
 
-A message sent in response to a Connect request when interactive authorization is needed:
+A message sent in response to a Connect request when interactive authorization is needed. This message follows the specification defined in [TAIP-4] for interactive authorization flows.
 
 - `@context` - REQUIRED the JSON-LD context `https://tap.rsvp/schema/1.0`
 - `@type` - REQUIRED the JSON-LD type `https://tap.rsvp/schema/1.0#AuthorizationRequired`
-- `authorization_url` - REQUIRED string URL where the user can authorize the connection
+- `authorizationUrl` - REQUIRED string URL where the user can authorize the connection
 - `expires` - REQUIRED string ISO 8601 timestamp when the authorization URL expires
+- `from` - OPTIONAL the party type (e.g., `customer`, `principal`, or `originator`) that is required to open the URL
+
+For the complete specification of this message type, see [TAIP-4].
 
 ### Authorize Message
 
@@ -359,7 +362,7 @@ The following are example plaintext messages. See [TAIP-2] for how to sign the m
   "body": {
     "@context": "https://tap.rsvp/schema/1.0",
     "@type": "https://tap.rsvp/schema/1.0#AuthorizationRequired",
-    "authorization_url": "https://vasp.com/authorize?request=abc123",
+    "authorizationUrl": "https://vasp.com/authorize?request=abc123",
     "expires": "2024-03-22T15:00:00Z"
   }
 }
diff --git a/TAIPs/taip-4.md b/TAIPs/taip-4.md
@@ -5,7 +5,7 @@ author: Pelle Braendgaard <pelle@notabene.id>, Andrés Junge <andres@notabene.id
 status: Last Call
 type: Standard
 created: 2024-01-12
-updated: 2025-07-28
+updated: 2025-08-03
 description: A protocol framework enabling off-chain authorization of blockchain transactions through DID-based agents before settlement. Separates transaction ordering, authorization, and settlement into distinct phases to address compliance, risk management, and operational challenges without changing permissionless blockchain characteristics.
 discussions-to: https://github.com/TransactionAuthorizationProtocol/TAIPs/pull/6
 requires: 2, 5
@@ -89,8 +89,9 @@ Messages implement [TAIP-2] and are sent between [TAIP-5 Agents][TAIP-5] after a
 
 It is essential to understand that this is, strictly speaking, a messaging standard. No shared state is implied between agents except the ultimate settlement on a blockchain.
 
-There are three primary actions an agent can take:
+There are four primary actions an agent can take:
 
+- `AuthorizationRequired` - Request that an end user opens an authorization URL to approve the transaction.
 - `Settle` - They announce they will send the transaction to the blockchain.
 - `Authorize` - Authorize or signal to other agents that they are free to `settle` a transaction.
 - `Cancel` - Signal to other agents that they are canceling the transaction.
@@ -99,6 +100,16 @@ There are three primary actions an agent can take:
 
 All messages are sent as replies to an initial request by specifying the `id` of the original request in the `thid` attribute.
 
+### AuthorizationRequired
+
+Any agent can require that an end user opens up an authorization URL in a web browser or app before proceeding with the transaction. An agent may require this to ensure that the end user authorizes a payment. The following shows the attributes of the `body` object:
+
+- `@context` - REQUIRED the JSON-LD context `https://tap.rsvp/schema/1.0`
+- `@type` - REQUIRED the JSON-LD type `https://tap.rsvp/schema/1.0#AuthorizationRequired`
+- `authorizationUrl` - REQUIRED string URL where the user can authorize the transaction
+- `expires` - REQUIRED string ISO 8601 timestamp when the authorization URL expires
+- `from` - OPTIONAL the party type (e.g., `customer`, `principal`, or `originator`) that is required to open the URL
+
 ### Authorize
 
 Any agent can authorize the transaction by replying as a thread to the initial message. The following shows the attributes of the `body` object:
@@ -364,6 +375,24 @@ It is very important to understand that messages are just messages. Agents may o
 <!--Please add diverse test cases here if applicable. Any normative definition of an interface requires test cases to be implementable. -->
 The following are example plaintext messages. See [TAIP-2] for how to sign the messages.
 
+### AuthorizationRequired
+
+```json
+{
+  "from": "did:web:beneficiary.vasp",
+  "type": "https://tap.rsvp/schema/1.0#AuthorizationRequired",
+  "thid": "ID of transfer request",
+  "to": ["did:web:originator.vasp"],
+  "body": {
+    "@context": "https://tap.rsvp/schema/1.0",
+    "@type": "https://tap.rsvp/schema/1.0#AuthorizationRequired",
+    "authorizationUrl": "https://beneficiary.vasp/authorize?request=abc123",
+    "expires": "2024-01-01T12:00:00Z",
+    "from": "customer"
+  }
+}
+```
+
 ### Authorize
 
 ```json
diff --git a/messages.md b/messages.md
@@ -14,6 +14,7 @@ permalink: /messages/
   - [Payment](#payment)
   - [Escrow](#escrow)
 - [Authorization Flow Messages](#authorization-flow-messages)
+  - [AuthorizationRequired](#authorizationrequired)
   - [Authorize](#authorize)
   - [Settle](#settle)
   - [Reject](#reject)
@@ -423,6 +424,40 @@ Requests an agent to hold assets in escrow on behalf of parties, enabling paymen
 
 ## Authorization Flow Messages
 
+### AuthorizationRequired
+[TAIP-4] - Review
+
+An agent can require that an end user opens up an authorization URL in a web browser or app before proceeding with the transaction. An agent may require this to ensure that the end user authorizes a payment.
+
+| Attribute | Type | Required | Status | Description |
+|-----------|------|----------|---------|-------------|
+| @context | string | Yes | Review ([TAIP-4]) | JSON-LD context "https://tap.rsvp/schema/1.0" |
+| @type | string | Yes | Review ([TAIP-4]) | JSON-LD type "https://tap.rsvp/schema/1.0#AuthorizationRequired" |
+| authorizationUrl | string | Yes | Review ([TAIP-4]) | URL where the user can authorize the transaction |
+| expires | string | Yes | Review ([TAIP-4]) | ISO 8601 timestamp when the authorization URL expires |
+| from | string | No | Review ([TAIP-4]) | Optional party type (e.g., "customer", "principal", or "originator") that is required to open the URL |
+
+> **Note:** The message refers to the original Transfer or Payment message via the DIDComm `thid` (thread ID) in the message envelope.
+
+#### Examples
+
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174001",
+  "type": "https://tap.rsvp/schema/1.0#AuthorizationRequired",
+  "from": "did:web:beneficiary.vasp",
+  "to": ["did:web:originator.vasp"],
+  "thid": "123e4567-e89b-12d3-a456-426614174000",
+  "body": {
+    "@context": "https://tap.rsvp/schema/1.0",
+    "@type": "https://tap.rsvp/schema/1.0#AuthorizationRequired",
+    "authorizationUrl": "https://beneficiary.vasp/authorize?request=abc123",
+    "expires": "2024-01-01T12:00:00Z",
+    "from": "customer"
+  }
+}
+```
+
 ### Authorize
 [TAIP-4] - Review
 
@@ -1060,7 +1095,7 @@ The body object must contain:
   "body": {
     "@context": "https://tap.rsvp/schema/1.0",
     "@type": "https://tap.rsvp/schema/1.0#AuthorizationRequired",
-    "authorization_url": "https://beneficiary.vasp/authorize?request=abc123",
+    "authorizationUrl": "https://beneficiary.vasp/authorize?request=abc123",
     "expires": "2024-03-22T15:00:00Z"
   }
 }
@@ -1078,7 +1113,7 @@ The body object must contain:
   "body": {
     "@context": "https://tap.rsvp/schema/1.0",
     "@type": "https://tap.rsvp/schema/1.0#AuthorizationRequired",
-    "authorization_url": "https://payment.provider/merchant/onboard?id=xyz789",
+    "authorizationUrl": "https://payment.provider/merchant/onboard?id=xyz789",
     "expires": "2024-03-22T15:00:00Z"
   }
 }
@@ -1188,7 +1223,7 @@ Provides an authorization URL for interactive connection approval.
 |-----------|------|----------|---------|-------------|
 | @context | string | Yes | Draft ([TAIP-15]) | JSON-LD context "https://tap.rsvp/schema/1.0" |
 | @type | string | Yes | Draft ([TAIP-15]) | JSON-LD type "https://tap.rsvp/schema/1.0#AuthorizationRequired" |
-| authorization_url | string | Yes | Draft ([TAIP-15]) | URL where the customer can review and approve the connection |
+| authorizationUrl | string | Yes | Draft ([TAIP-15]) | URL where the customer can review and approve the connection |
 | expires | string | Yes | Draft ([TAIP-15]) | ISO 8601 timestamp when the authorization URL expires |
 
 #### Example AuthorizationRequired Message
@@ -1204,7 +1239,7 @@ Provides an authorization URL for interactive connection approval.
   "body": {
     "@context": "https://tap.rsvp/schema/1.0",
     "@type": "https://tap.rsvp/schema/1.0#AuthorizationRequired",
-    "authorization_url": "https://vasp.com/authorize?request=abc123",
+    "authorizationUrl": "https://vasp.com/authorize?request=abc123",
     "expires": "2024-03-22T15:00:00Z"
   }
 }
@@ -1266,7 +1301,7 @@ This flow demonstrates establishing a connection between a B2B service and a VAS
   "body": {
     "@context": "https://tap.rsvp/schema/1.0",
     "@type": "https://tap.rsvp/schema/1.0#AuthorizationRequired",
-    "authorization_url": "https://vasp.com/authorize?request=abc123",
+    "authorizationUrl": "https://vasp.com/authorize?request=abc123",
     "expires": "2024-03-22T15:00:00Z"
   }
 }
diff --git a/packages/typescript/src/tap.ts b/packages/typescript/src/tap.ts
@@ -428,12 +428,19 @@ export interface Agent extends Partial<Organization> {
    * is resolvable from the agent's DID document. Particularly useful for self-hosted
    * and decentralized agents. For security purposes, this field SHOULD be ignored
    * if a valid DIDComm service endpoint is already listed in the DID document.
-   * 
+   *
    * @example "https://agent.example.com/didcomm"
    */
   serviceUrl?: IRI;
 }
 
+type PartyType =
+  | "originator"
+  | "beneficiary"
+  | "customer"
+  | "merchant"
+  | "principal";
+
 /**
  * Base interface for all TAP policy types.
  * Policies define requirements and constraints that must be satisfied during a transaction.
@@ -463,7 +470,7 @@ export interface Policy<T extends string> extends JsonLdObject<T> {
    * Optional agent representing a party required to fulfill this policy
    * E.g. 'originator' or 'beneficiary' in TAIP-3
    */
-  fromAgent?: "originator" | "beneficiary" | "customer" | "merchant";
+  fromAgent?: PartyType;
 
   /**
    * Optional human-readable description of the policy's purpose
@@ -1108,17 +1115,30 @@ export interface TransactionConstraints {
 
 /**
  * Authorization Required Message
- * Response providing an authorization URL for connection approval.
+ * Response providing an authorization URL for transaction or connection approval.
+ * An agent can require that an end user opens up the authorizationUrl in a web browser or app.
+ * An agent may require this to ensure that the end user authorizes a payment or connection.
  *
+ * @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-4.md | TAIP-4: Transaction Authorization Protocol}
  * @see {@link https://github.com/TransactionAuthorizationProtocol/TAIPs/blob/main/TAIPs/taip-15.md | TAIP-15: Agent Connection Protocol}
  */
 export interface AuthorizationRequired
   extends TapMessageObject<"AuthorizationRequired"> {
   /**
-   * URL for connection authorization
-   * Where the customer can review and approve
+   * URL for authorization
+   * Where the user can authorize the transaction or connection
+   */
+  authorizationUrl: string;
+
+  /**
+   * Optional party type required to open the URL
+   * Indicates the party type (e.g., "customer", "principal", or "originator") that is required to open the URL
+   *
+   * @example "customer"
+   * @example "principal" 
+   * @example "originator"
    */
-  authorization_url: string;
+  from?: PartyType;
 
   /**
    * Expiration timestamp
diff --git a/test-vectors/authorization-required/valid-authorization-required.json b/test-vectors/authorization-required/valid-authorization-required.json
@@ -15,7 +15,7 @@
     "body": {
       "@context": "https://tap.rsvp/schema/1.0",
       "@type": "https://tap.rsvp/schema/1.0#AuthorizationRequired",
-      "authorization_url": "https://vasp.example/authorize?request=abc123",
+      "authorizationUrl": "https://vasp.example/authorize?request=abc123",
       "expires": "2024-03-22T15:00:00Z"
     }
   },

Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,7 @@`
`15`	`15`	`"body": {`
`16`	`16`	`"@context": "https://tap.rsvp/schema/1.0",`
`17`	`17`	`"@type": "https://tap.rsvp/schema/1.0#AuthorizationRequired",`
`18`		`- "authorization_url": "https://vasp.example/authorize?request=abc123",`
	`18`	`+ "authorizationUrl": "https://vasp.example/authorize?request=abc123",`
`19`	`19`	`"expires": "2024-03-22T15:00:00Z"`
`20`	`20`	`}`
`21`	`21`	`},`