Skip to content

ADR 8: PII field usage in GET API endpoints

Status

accepted

Context

As a general rule, PII should not be used in the url of a REST API. From JX-R:

A data security rule for the JX-R API is to place highly sensitive data (generally encrypted as appropriate) into the body or header of the API call. This may require the API to be defined as a POST instead of a GET in situations where a GET would be commonly used.

Considered PII

Based on the JHA Data Classification Policy 2021 via the Policy Center, the following fields have been identified as PII in existing APIs:

  • ExternalEntityIdentifier
  • In our case, this is normally of type other with a guid value from Banno, however there is no expectation that it couldn’t be used with the other types. This field is present in a few GET calls.
  • CoreCustomerId
  • Could be PII depending on the data point used by the FI
  • CIF except for Episys (SSN)
  • Financial account
  • Token (SMS/email)
  • Actual name or alias
  • Physical address

Not Considered PII

  • Service-level identifier such as guid or identify/NHILO
  • Generated ID such as ZelleId
  • IP Address
  • IPs are tier 2. Can be classified as PII if related to other data. Since we are filtering other PII, IP addresses do not need to be filtered out.

Decision

Approaches considered

Switch queries to POST

Likely would entail something like a /searches endpoint. This would involve a bit more work but would be easier to grok as all fields are treated the same.

Use a verb override

From here

GET /lines/8665551212

becomes:

X-HTTP-Method-Override:GET POST /lines { "phoneNumber":"8665551212" }

I like this approach but could be a bit confusing having the same url/verb perform different things in certain cases.

Move to header

Regain GET endpoints, but move PII fields to header. This is the smaller refactor at the cost of inconsistency. 

BSV-ExternalEntityId:421552323
GET /users/activity/?startOn=2021-10-10

Per RFC6648, the project-specific prefix of BSV- is used in favor of X-.

Approach decided

The move to header approach has the smallest impact.

Consequences

  • The OpenAPI spec will require that PII fields are specified as a header rather than query param.
  • Controller code will need to manage header query fields in the handful of cases where they are used.
  • At last count, 8 endpoints use PII but only 3 have been implemented.