Download OpenAPI specification:Download
In order to improve trust in the open banking ecosystem, this work proposes a protocol for traceability---the ability for consumers to track how data is being used and shared, even (and especially) across organizational boundaries. Traceability will help achieve reliable, scalable detection of data misuse, leading to both better internal processes and more effective intervention by enforcement authorities when necessary.
The main participants in the open banking ecosystem are:
To facilitate traceability, we introduce the idea of a traceability service, which stores traceability information on behalf of consumers. Traceability services have three deployment models:
These traceability services will record various types of traceability attestations:
A traceability protocol is comprised of several subprotocols:
Version | Description | Date | Author |
---|---|---|---|
0.1 | Initital Verision | 3/17/2024 | Dean Wen |
0.2 | Updated Introduction | 3/30/2024 | Kevin Liao |
0.3 | Added user dashboard and violation notify API | 4/12/2024 | Dean Wen |
0.4 | Revised consents and data APIs, de-scope migration APIs | 5/12/2024 | Dean Wen |
0.5 | Added more endpoints, switched to Python FastAPI | 5/1/2025 | Ashar Farooq |
consumer required | string (Consumer) |
operator required | string (Operator) |
service required | string (Service) |
{- "consumer": "string",
- "operator": "string",
- "service": "string"
}
null
Record an attestation for a specific party.
party_name required | string (Party Name) |
data_controller required | string (Data Controller) |
type required | string (Action_Type) Enum: "consent offered" "consent revoked" "consent accepted" "consent denied" "authorization granted" "authorization revoked" "data subject request: make" "data subject request: receive" "data subject request: update" "data use" "introduction" |
required | object (Information) |
{- "type": "consent offered",
- "information": { }
}
{- "id": "string",
- "party": {
- "name": "string",
- "data_controller": "consumer"
}, - "action": {
- "type": "consent offered",
- "information": { }
}, - "timestamp": "2019-08-24T14:15:22Z"
}
Get all attestations for a specific party.
party_name required | string (Party Name) |
[- {
- "id": "string",
- "party": {
- "name": "string",
- "data_controller": "consumer"
}, - "action": {
- "type": "consent offered",
- "information": { }
}, - "timestamp": "2019-08-24T14:15:22Z"
}
]
Get attestations for a party that fall within the specified timestamp range.
party_name required | string (Party Name) |
start_time required | string <date-time> (Start Time) |
end_time required | string <date-time> (End Time) |
[- {
- "id": "string",
- "party": {
- "name": "string",
- "data_controller": "consumer"
}, - "action": {
- "type": "consent offered",
- "information": { }
}, - "timestamp": "2019-08-24T14:15:22Z"
}
]
Operator offers consent to the user for using certain data for certain operations until the expiry time.
expiry_timestamp required | string <date-time> (Expiry Timestamp) |
required | object (Operator) |
required | object (User) |
required | object (Data) |
required | Array of objects (Operations) |
{- "operator": {
- "name": "string"
}, - "user": {
- "name": "string"
}, - "data": {
- "description": "string"
}, - "operations": [
- {
- "operation_type": "read"
}
]
}
{- "id": "string",
- "operator": {
- "name": "string"
}, - "user": {
- "name": "string"
}, - "data": {
- "description": "string"
}, - "operations_permitted": [
- {
- "operation_type": "read"
}
], - "expiry_timestamp": "2019-08-24T14:15:22Z",
- "state": "offered"
}
User accepts an offered consent.
consent_id required | string <uuid> (Consent Id) |
name required | string (Name) |
{- "name": "string"
}
null
User denies an offered consent.
consent_id required | string <uuid> (Consent Id) |
name required | string (Name) |
{- "name": "string"
}
null
User revokes a consent, moving it from accepted to denied.
consent_id required | string <uuid> (Consent Id) |
name required | string (Name) |
{- "name": "string"
}
null
Get a consent object by its ID.
consent_id required | string <uuid> (Consent Id) |
{- "id": "string",
- "operator": {
- "name": "string"
}, - "user": {
- "name": "string"
}, - "data": {
- "description": "string"
}, - "operations_permitted": [
- {
- "operation_type": "read"
}
], - "expiry_timestamp": "2019-08-24T14:15:22Z",
- "state": "offered"
}
List all offered, accepted, and denied consents for a user.
user_name required | string (User Name) |
[- {
- "id": "string",
- "operator": {
- "name": "string"
}, - "user": {
- "name": "string"
}, - "data": {
- "description": "string"
}, - "operations_permitted": [
- {
- "operation_type": "read"
}
], - "expiry_timestamp": "2019-08-24T14:15:22Z",
- "state": "offered"
}
]
Operator records the use of data from a subject for an operation under a basis.
required | object (Operator) |
required | object (Data) |
required | object (DataSubject) |
required | object (Operation) |
required | object (Basis) |
{- "operator": {
- "name": "string"
}, - "data": {
- "description": "string"
}, - "data_subject": {
- "name": "string"
}, - "operation": {
- "operation_type": "read"
}, - "basis": {
- "base_type": "consent",
- "basis_object": null
}
}
{- "id": "string",
- "operator": {
- "name": "string"
}, - "data": {
- "description": "string"
}, - "data_subject": {
- "name": "string"
}, - "operation": {
- "operation_type": "read"
}, - "basis": {
- "base_type": "consent",
- "basis_object": null
}, - "timestamp": "2019-08-24T14:15:22Z"
}
Allows a subject to send a data subject request to a controller.
subject required | string (Subject) |
controller required | string (Controller) |
request_type required | string (RequestType) Enum: "Access Request" "Correction Request" "Delete Request" "Output Request" |
null
Updates the status of a data subject request.
request_id required | string (Request Id) |
status required | string (RequestStatus) Enum: "Received" "Completed" "Denied" |
null
Search for attestations using multiple filters.
required | Party Name (string) or Party Name (null) (Party Name) |
required | Data Controller (string) or Data Controller (null) (Data Controller) |
required | Action_Type (string) or Action Type (null) (Action Type) |
required | Provider (string) or Provider (null) (Provider) |
required | User (string) or User (null) (User) |
required | Consent (string) or Consent (null) (Consent) |
required | Start Time (string) or Start Time (null) (Start Time) |
required | End Time (string) or End Time (null) (End Time) |
[- {
- "id": "string",
- "party": {
- "name": "string",
- "data_controller": "consumer"
}, - "action": {
- "type": "consent offered",
- "information": { }
}, - "timestamp": "2019-08-24T14:15:22Z"
}
]
Checks whether an attestation (data use) is valid under a given consent (basis). Returns True if it is valid, or False otherwise.
data_use_id required | string (Data Use Id) |
consent_id required | string (Consent Id) |
null