[Or.0.1] As am orchestrator, I should be able to connect to Request Network API via a client ID and subscribe to a webhook to listen to a given destination's request #171
Description
This spec defines how an orchestrator integrates with Request via Client IDs that are issued by a recipient/destination owner. A Client ID is scoped by default, so an orchestrator can only create and read the objects they are authorized to handle. Webhooks are the primary mechanism for receiving status updates.
User stories
As an orchestrator, once I am given a Client ID by a recipient who has claimed a destination, I should be able to authenticate to the Request API using that Client ID.
As an orchestrator, using my Client ID, I should be able to register and manage a webhook endpoint to receive event notifications related to requests I am authorized to access.
As an orchestrator, using my Client ID, I should be able to create incoming or outgoing requests on behalf of the destination associated with that Client ID.
As an orchestrator, using my Client ID, I should be able to generate a payment link for any incoming or outgoing requests I created under the destination associated with that Client ID.
As an orchestrator, using my Client ID, I should be able to retrieve the status of any request I created under the destination associated with that Client ID.
As an orchestrator, using my Client ID, I should be able to receive webhook events for status updates of the requests I created.
As an orchestrator, using my Client ID, I should not be able to view, query, or receive webhook notifications for requests created by other orchestrators using different Client IDs, even if those requests are under the same destination.
As an orchestrator, I should not be able to create requests for destinations that are not associated with my Client ID.
As an orchestrator, I should not be able to subscribe to webhook events outside of the scope granted by my Client ID.
⸻
Future access scopes and roles
As an orchestrator, I should be able to be granted a read:incoming permission that allows me to view and receive webhook notifications for all incoming requests under a given destination, including those created by other orchestrators.
As an orchestrator, I should be able to be granted a read:outgoing permission that allows me to view and receive webhook notifications for all outgoing requests under a given destination, including those created by other orchestrators.
As an orchestrator, I should be able to be granted a create:incoming permission that allows me to create incoming requests and generate payment links, and receive status updates on behalf of a given destination.
As an orchestrator, I should be able to be granted a create:outgoing permission that allows me to create outgoing (disbursement) requests, generate payment links, and receive status updates on behalf of a given destination.
⸻
Product requirements (spec-level)
Client ID scoping must default to least privilege, where an orchestrator can only access requests that it created, unless additional permissions are explicitly granted.
Webhook subscriptions must respect Client ID scope, ensuring the orchestrator only receives events for requests it is authorized to read.
The destination owner must be able to grant or revoke orchestrator permissions independently per Client ID.
Request creation endpoints must enforce destination scoping so that an orchestrator cannot create requests outside the destination associated with its Client ID.
Request read endpoints must enforce isolation so that orchestrators cannot see each other’s requests unless they have a destination-wide read permission.
Outgoing and incoming must be treated as separate domains for authorization, so that access can be granted independently for each direction.
Status retrieval and webhook delivery must be consistent, meaning any status an orchestrator can fetch via API is also eligible to be delivered via webhook, and anything out of scope must not be delivered by either channel.