Otrace API (0.5)

Download OpenAPI specification:Download

Introduction

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:

  1. Consumers. Individuals who want to use digital financial services.
  2. Data providers. Companies (e.g., traditional banks, payment providers, credit card providers) that hold consumer financial data.
  3. Data recipients. Companies (e.g., fintechs, payment processors, credit reference agencies, regulators) that use consumer financial data to provide requested services.
  4. Data access platforms. Intermediaries (e.g., API providers, data aggregators) that support data exchange between data providers and data recipients.

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:

  1. Self-hosted. Consumers self-host traceability services on their personal machines or in the cloud.
  2. Third-party-hosted. Third-party providers (e.g., nongovernmental organizations, private companies) host traceability services.
  3. Provider-hosted. Data providers host traceability services (given their existing trust relationships with consumers).

These traceability services will record various types of traceability attestations:

  1. Policy attestations. These describe agreed-upon terms of granular consent, delineating the relevant data types, their intended usage, the duration of data retention, the conditions under which data may be reshared, and logging requirements.
  2. Sharing attestations. These describe sharing actions on data elements includes information, such as the timestamps and purposes of sharing.
  3. Activity attestations. These describe local actions on data elements (e.g., use, deletion) and includes information, such as the timestamps and purposes of the actions.
  4. Rights attestations. These describe actions associated with data rights requests, such as consent grant, consent revocation, data access, data correction, and data deletion.

A traceability protocol is comprised of several subprotocols:

  1. Traceability setup. This is a three-party protocol, involving a consumer, data controller (i.e., a data provider or a data recipient), and traceability service. The consumer authorizes the controller to interact with the traceability service on its behalf. Concretely, this can be implemented using OAuth, where the controller (either a data provider or a data recipient) is an OAuth client and the traceability service acts as the authorization and resource servers.
  2. Data sharing setup. This is a four-party protocol, involving a consumer, data provider, data recipient, and traceability service. The consumer initiates data sharing between the provider and the recipient (e.g., using the FDX protocol), and the recipient and provider both post consent records to the traceability service.
  3. Data sharing. This is a three-party protocol, involving a data provider, data recipient, and traceability service. The recipient requests data from the provider (e.g., using the FDX protocol), and receives the data and a "consentID" in return. Finally, the recipient and provider both post sharing attestations to the traceability service.
  4. Data use. This is a two-party protocol, involving a data controller and traceability service. The controller posts an activity attestation to the traceability service.
  5. Consumer rights request. This is a three-party protocol, involving a consumer, controller, and traceability service based on the Data Rights Protocol (DRP). The consumer initiates a rights request with the traceability service, which forwards the request to the controller. The controller posts a rights attestation to the traceability service.

Terms and Definitions

Terms Definition
OAuth OAuth
FDX FDX
HTTP HTTP

Change History

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

Introduction

Introduce

Authorizations:
OAuth2PasswordBearer
Request Body schema: application/json
consumer
required
string (Consumer)
operator
required
string (Operator)
service
required
string (Service)

Responses

Request samples

Content type
application/json
{
  • "consumer": "string",
  • "operator": "string",
  • "service": "string"
}

Response samples

Content type
application/json
null

Introduced

Checks if an operator is connected to any service on behalf of a consumer.

Authorizations:
OAuth2PasswordBearer
query Parameters
consumer
required
string (Consumer)
operator
required
string (Operator)

Responses

Response samples

Content type
application/json
null

Attestations

Attest

Record an attestation for a specific party.

Authorizations:
OAuth2PasswordBearer
path Parameters
party_name
required
string (Party Name)
data_controller
required
string (Data Controller)
Request Body schema: application/json
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)

Responses

Request samples

Content type
application/json
{
  • "type": "consent offered",
  • "information": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "party": {
    },
  • "action": {
    },
  • "timestamp": "2019-08-24T14:15:22Z"
}

Get All Attestations

Get all attestations for a specific party.

Authorizations:
OAuth2PasswordBearer
path Parameters
party_name
required
string (Party Name)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Up To Date Attestations

Get attestations for a party that fall within the specified timestamp range.

Authorizations:
OAuth2PasswordBearer
path Parameters
party_name
required
string (Party Name)
query Parameters
start_time
required
string <date-time> (Start Time)
end_time
required
string <date-time> (End Time)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Consents

Offer Consent

Operator offers consent to the user for using certain data for certain operations until the expiry time.

Authorizations:
OAuth2PasswordBearer
query Parameters
expiry_timestamp
required
string <date-time> (Expiry Timestamp)
Request Body schema: application/json
required
object (Operator)
required
object (User)
required
object (Data)
required
Array of objects (Operations)

Responses

Request samples

Content type
application/json
{
  • "operator": {
    },
  • "user": {
    },
  • "data": {
    },
  • "operations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "operator": {
    },
  • "user": {
    },
  • "data": {
    },
  • "operations_permitted": [
    ],
  • "expiry_timestamp": "2019-08-24T14:15:22Z",
  • "state": "offered"
}

Accept Consent

User accepts an offered consent.

Authorizations:
OAuth2PasswordBearer
path Parameters
consent_id
required
string <uuid> (Consent Id)
Request Body schema: application/json
name
required
string (Name)

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
null

Deny Consent

User denies an offered consent.

Authorizations:
OAuth2PasswordBearer
path Parameters
consent_id
required
string <uuid> (Consent Id)
Request Body schema: application/json
name
required
string (Name)

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
null

Revoke Consent

User revokes a consent, moving it from accepted to denied.

Authorizations:
OAuth2PasswordBearer
path Parameters
consent_id
required
string <uuid> (Consent Id)
Request Body schema: application/json
name
required
string (Name)

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
null

List User Consents

List all offered, accepted, and denied consents for a user.

Authorizations:
OAuth2PasswordBearer
path Parameters
user_name
required
string (User Name)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Data Use

Record Data Use

Operator records the use of data from a subject for an operation under a basis.

Authorizations:
OAuth2PasswordBearer
Request Body schema: application/json
required
object (Operator)
required
object (Data)
required
object (DataSubject)
required
object (Operation)
required
object (Basis)

Responses

Request samples

Content type
application/json
{
  • "operator": {
    },
  • "data": {
    },
  • "data_subject": {
    },
  • "operation": {
    },
  • "basis": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "operator": {
    },
  • "data": {
    },
  • "data_subject": {
    },
  • "operation": {
    },
  • "basis": {
    },
  • "timestamp": "2019-08-24T14:15:22Z"
}

Get Basis

Get the basis of the data use by ID.

Authorizations:
OAuth2PasswordBearer
path Parameters
data_use_id
required
string <uuid> (Data Use Id)

Responses

Response samples

Content type
application/json
{
  • "base_type": "consent",
  • "basis_object": null
}

Data Subject Request

Send Request

Allows a subject to send a data subject request to a controller.

Authorizations:
OAuth2PasswordBearer
query Parameters
subject
required
string (Subject)
controller
required
string (Controller)
request_type
required
string (RequestType)
Enum: "Access Request" "Correction Request" "Delete Request" "Output Request"

Responses

Response samples

Content type
application/json
null

Get Request

Retrieves a data subject request by its id.

Authorizations:
OAuth2PasswordBearer
path Parameters
request_id
required
string (Request Id)

Responses

Response samples

Content type
application/json
null

Update Request Status

Updates the status of a data subject request.

Authorizations:
OAuth2PasswordBearer
path Parameters
request_id
required
string (Request Id)
query Parameters
status
required
string (RequestStatus)
Enum: "Received" "Completed" "Denied"

Responses

Response samples

Content type
application/json
null

Trace

Search Attestations

Search for attestations using multiple filters.

Authorizations:
OAuth2PasswordBearer
query Parameters
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)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Check

Home

Responses

Response samples

Content type
application/json
null