## Implementation

Page tokens **should** be versioned independently of the public API, so that
page tokens can be used with any version of the service.

The simplest form of a page token only requires an offset. However, offsets
pose challenges when a distributed database is introduced, so a more robust
page token needs to store the information needed to find a "logical" position
in the database. The simplest way to do this is to include relevant data from
the last result returned. Primarily, this means the resource ID, but also
includes any other fields from the resource used to sort the results (for the
event where the resource is changed or deleted).

This information is from the resource itself, and therefore might be sensitive.
Sensitive data **must** be encrypted before being used in a page token.
Therefore, the token also includes the date it was created, to allow for the
potential need to rotate the encryption key.

This yields the following interface, which **may** be base64 encoded and used
as a page token:

\```typescript
interface PageTokenSecrets {
  // The ID of the most recent resource returned.
  lastId: string;

  // Any index data needed, generally 1:1 with the fields used for ordering.
  indexData: Buffer[];

  // When this token was minted.
  createTime: Date;
}
\```

**Note:** This section does not preclude alternative page token implementations