Skip to content

API reference

This page is generated from vfps's .proto files, which define the API. Every RPC is served over gRPC and, where a REST route is listed, as JSON over HTTP. In JSON, field names are written in camelCase (original_value becomes originalValue) and enum values by name. See the gRPC API guide for how to call them, and the latest release for the .proto files as a versioned download.

NamespaceService

service for managing pseudonym namespaces

NamespaceService.Create

POST /v1/namespaces

create a new namespace for pseudonyms

Request: NamespaceServiceCreateRequest · Response: NamespaceServiceCreateResponse

NamespaceService.Get

GET /v1/namespaces/{name}

get information about a namespace

Request: NamespaceServiceGetRequest · Response: NamespaceServiceGetResponse

NamespaceService.List

GET /v1/namespaces

list all namespaces the caller can read

Request: NamespaceServiceListRequest · Response: NamespaceServiceListResponse

NamespaceService.GetAll

deprecated: use List, which returns the same namespaces. Kept for existing gRPC clients only - the REST route GET /v1/namespaces now belongs to List and answers with the same JSON.

Request: NamespaceServiceGetAllRequest · Response: NamespaceServiceGetAllResponse

NamespaceService.Update

PATCH /v1/namespaces/{namespace.name}

update the parts of a namespace that can change after creation: its description and its original value validation regex. Every other field shapes how pseudonyms are generated or how the namespace relates to others, and is fixed at creation. Requires admin access.

A partial update following AIP-134 (https://google.aip.dev/134): update_mask names the fields to change, and a field named there but absent from the request is cleared. Without an update_mask, every updatable field that is set in the request is changed and the rest are kept; "*" replaces every updatable field. Naming a field that can't change is INVALID_ARGUMENT. A changed regex only applies to original values new to the namespace.

Request: NamespaceServiceUpdateRequest · Response: NamespaceServiceUpdateResponse

NamespaceService.Delete

DELETE /v1/namespaces/{name}

delete a namespace and all pseudonyms it contains

Request: NamespaceServiceDeleteRequest · Response: NamespaceServiceDeleteResponse

NamespaceService.ListChildren

GET /v1/namespaces/{name}/children

list the direct children of a namespace. Non-recursive: callers wanting a full subtree call this once per level.

Request: NamespaceServiceListChildrenRequest · Response: NamespaceServiceListChildrenResponse

ProjectService

service for managing projects: named groups of namespaces that belong together, e.g. the namespaces holding the patient-id and encounter-id pseudonyms of one study.

Projects only group namespaces for organization. They carry no access rules of their own - access is still granted per namespace - and a caller only ever sees the namespaces of a project that they can read. A namespace can be part of any number of projects.

ProjectService.Create

POST /v1/projects

create a new, empty project. Requires admin access.

Request: ProjectServiceCreateRequest · Response: ProjectServiceCreateResponse

ProjectService.Get

GET /v1/projects/{name}

get a project and the names of the namespaces in it

Request: ProjectServiceGetRequest · Response: ProjectServiceGetResponse

ProjectService.List

GET /v1/projects

list all projects the caller can see

Request: ProjectServiceListRequest · Response: ProjectServiceListResponse

ProjectService.Update

PATCH /v1/projects/{project.name}

update a project's description, the only part of a project that can change: its name is its identity, and its namespaces are changed with AddNamespace and RemoveNamespace. Requires admin access.

A partial update following AIP-134 (https://google.aip.dev/134), exactly like NamespaceService.Update: update_mask names the fields to change, and a field named there but absent from the request is cleared.

Request: ProjectServiceUpdateRequest · Response: ProjectServiceUpdateResponse

ProjectService.Delete

DELETE /v1/projects/{name}

delete a project. The namespaces in it, and their pseudonyms, are not affected. Requires admin access.

Request: ProjectServiceDeleteRequest · Response: ProjectServiceDeleteResponse

ProjectService.AddNamespace

PUT /v1/projects/{name}/namespaces/{namespace}

add a namespace to a project. Succeeds without changes if it is already part of it. Requires admin access.

Request: ProjectServiceAddNamespaceRequest · Response: ProjectServiceAddNamespaceResponse

ProjectService.RemoveNamespace

DELETE /v1/projects/{name}/namespaces/{namespace}

remove a namespace from a project. Succeeds without changes if it isn't part of it. Requires admin access.

Request: ProjectServiceRemoveNamespaceRequest · Response: ProjectServiceRemoveNamespaceResponse

PseudonymService

service to manage pseudonyms

PseudonymService.Create

POST /v1/namespaces/{namespace}/pseudonyms

create a new pseudonym in the given namespace for an original value

Request: PseudonymServiceCreateRequest · Response: PseudonymServiceCreateResponse

PseudonymService.Append

POST /v1/namespaces/{namespace}/pseudonyms:append

store one additional, newly generated pseudonym for an original value, appended after every pseudonym already stored for it. Only valid for a namespace with allows_multiple_pseudonyms set - FAILED_PRECONDITION otherwise. Requires the same write access Create does.

Unlike Create this is not idempotent by itself: every successful call stores another pseudonym. Set request_id to make it safe to retry (AIP-155): a call repeating the request_id of an earlier successful one stores nothing and returns the pseudonym that call stored.

Request: PseudonymServiceAppendRequest · Response: PseudonymServiceAppendResponse

PseudonymService.Import

POST /v1/namespaces/{namespace}/pseudonyms:import

store a pseudonym that was created outside vfps for an original value, verbatim. Only valid for a namespace using PSEUDONYM_GENERATION_METHOD_EXTERNAL - FAILED_PRECONDITION otherwise. Requires the same write access Create does.

Idempotent for the exact same pair: re-sending an already stored (original_value, pseudonym_value) succeeds and returns the stored pseudonym. Nothing is ever overwritten. ALREADY_EXISTS is returned when the pair conflicts with what is stored - the original value already has a different pseudonym (and the namespace doesn't allow multiple), or the pseudonym value already belongs to a different original value. The error never says which original value holds a pseudonym, as that would be a reverse lookup, which write access doesn't grant.

Request: PseudonymServiceImportRequest · Response: PseudonymServiceImportResponse

PseudonymService.Resolve

POST /v1/namespaces/{namespace}/pseudonyms:resolve

resolve the pseudonym already stored for an original value, creating nothing. Returns NOT_FOUND when the namespace holds none - the difference from Create, which would generate one. Requires the same write access Create does: this is the same forward mapping, and a caller who may create a pseudonym for a value may already learn it that way.

POST with the original value in the body, deliberately, even though this reads rather than writes: a GET would put the original value in the request path, where it would be recorded by every access log, proxy and browser history between the caller and this service. No operation on this API takes an original value in a URL.

Request: PseudonymServiceResolveRequest · Response: PseudonymServiceResolveResponse

PseudonymService.Get

GET /v1/namespaces/{namespace}/pseudonyms/{pseudonym_value}

reverse lookup: reveal the original value behind a pseudonym. The one operation that de-pseudonymizes, so it requires its own reverse-lookup permission - neither read nor write access grants it. The pseudonym value is in the URL; an original value never is.

Request: PseudonymServiceGetRequest · Response: PseudonymServiceGetResponse

PseudonymService.List

GET /v1/namespaces/{namespace}/pseudonyms

list all pseudonyms in the given namespace. Unlike Get, this never returns original_value - reverse lookup of a specific pseudonym is a separate, single-record operation by design.

Request: PseudonymServiceListRequest · Response: PseudonymServiceListResponse

Messages

Meta

metadata about an entity

Field Type Description
created_at google.protobuf.Timestamp time when the entity was created
last_updated_at google.protobuf.Timestamp time when the entity was last updated

Namespace

describes a pseudonym namespace

Field Type Description
meta Meta metadata about this entity
name string the name of the namespace
description optional string a description for the namespace. Absent when the namespace has none - stored as NULL rather than as an empty string, which is what a namespace created without one carries. optional like every other nullable-backed field here, so that "never given a description" and "given an empty one" stay distinguishable rather than both arriving as "".
pseudonym_generation_method PseudonymGenerationMethod the method to use when generating pseudonyms in the namespace
pseudonym_length uint32 the length of the pseudonym. Note that the total length depends on the generation method and excludes the prefix and suffix.
pseudonym_prefix optional string a prefix to prepend to each generated pseudonym
pseudonym_suffix optional string a suffix to append to each generated pseudonym
original_value_validation_regex optional string an optional regular expression used to validate an original value before a pseudonym is generated for it. If set, values that don't match are rejected with a client error. Can be changed after creation (from the admin UI); a changed pattern only applies to original values new to the namespace - values that already have a pseudonym keep resolving to it.
allows_multiple_pseudonyms bool when true, a single pseudonym Create call for this namespace may store more than one distinct pseudonym for the same original value.
parent_name optional string the name of this namespace's parent, if any. Absent means this namespace is a pseudonymization root: its original values are not pseudonyms of another namespace.
parent_validation_mode ParentValidationMode how original values are validated against the parent namespace. Only meaningful when parent_name is set.

NamespaceServiceCreateRequest

request to create a new namespace

Field Type Description
name string the name of the namespace to create. If a namespace with the same name alreay exists, an error is thrown
pseudonym_generation_method PseudonymGenerationMethod method to use when generating pseudonyms in this namespace
pseudonym_length uint32 the length of the pseudonym. Note that the total length depends on the generation method and excludes the prefix and suffix.
pseudonym_prefix optional string a prefix to prepend to each generated pseudonym
pseudonym_suffix optional string a suffix to append to each generated pseudonym
description optional string a description for the namespace. Omit it to store none at all; sending an empty string stores an empty description, and the two read back differently.
original_value_validation_regex optional string an optional regular expression used to validate an original value before a pseudonym is generated for it. If set, values that don't match are rejected with a client error.
allows_multiple_pseudonyms bool when true, a single pseudonym Create call for this namespace may store more than one distinct pseudonym for the same original value.
parent_name optional string the name of an existing namespace to set as this namespace's parent, making this a child namespace whose original values are pseudonyms of that parent. The parent must already exist. Immutable once the namespace is created.
parent_validation_mode ParentValidationMode how original values are validated against the parent namespace. Requires parent_name to be set.

NamespaceServiceCreateResponse

response for creating a namespace entity

Field Type Description
namespace Namespace the created namespace

NamespaceServiceDeleteRequest

request to delete a namespace and all pseudonyms it contains

Field Type Description
name string the name of the namespace to delete

NamespaceServiceDeleteResponse

response after deleting the namespace

This message has no fields.

NamespaceServiceGetAllRequest

request of the deprecated GetAll - see NamespaceServiceListRequest

This message has no fields.

NamespaceServiceGetAllResponse

response of the deprecated GetAll - see NamespaceServiceListResponse

Field Type Description
namespaces repeated Namespace every namespace the caller can read

NamespaceServiceGetRequest

request to get information about a namespace

Field Type Description
name string the name of the namespace

NamespaceServiceGetResponse

response for getting a namespace entity

Field Type Description
namespace Namespace the found namespace

NamespaceServiceListChildrenRequest

request to list the direct children of a namespace

Field Type Description
name string the name of the namespace whose direct children to list

NamespaceServiceListChildrenResponse

response listing the direct children of a namespace

Field Type Description
namespaces repeated Namespace the direct children of the requested namespace

NamespaceServiceListRequest

request to list all namespaces

This message has no fields.

NamespaceServiceListResponse

response listing all namespaces

Field Type Description
namespaces repeated Namespace every namespace the caller can read

NamespaceServiceUpdateRequest

request to update a namespace

Field Type Description
namespace Namespace the namespace to update, identified by its name, carrying the new values of the fields to change
update_mask google.protobuf.FieldMask the fields to change: description and/or original_value_validation_regex. See Update.

NamespaceServiceUpdateResponse

response for updating a namespace

Field Type Description
namespace Namespace the namespace as stored after the update

Project

describes a project

Field Type Description
meta Meta metadata about this entity
name string the name of the project
description optional string a description for the project. Absent when the project has none.
namespace_names repeated string the names of the namespaces in this project that the caller can read

ProjectServiceAddNamespaceRequest

request to add a namespace to a project

Field Type Description
name string the name of the project
namespace string the name of the namespace to add

ProjectServiceAddNamespaceResponse

response after adding a namespace to a project

This message has no fields.

ProjectServiceCreateRequest

request to create a project

Field Type Description
name string the name of the project to create. If a project with the same name already exists, an error is thrown
description optional string a description for the project. Omit it to store none at all.

ProjectServiceCreateResponse

response for creating a project

Field Type Description
project Project the created project

ProjectServiceDeleteRequest

request to delete a project

Field Type Description
name string the name of the project to delete

ProjectServiceDeleteResponse

response after deleting the project

This message has no fields.

ProjectServiceGetRequest

request to get a project

Field Type Description
name string the name of the project

ProjectServiceGetResponse

response for getting a project

Field Type Description
project Project the found project

ProjectServiceListRequest

request to list all projects

This message has no fields.

ProjectServiceListResponse

response listing all projects

Field Type Description
projects repeated Project the projects the caller can see: all of them for an admin, otherwise those with at least one namespace the caller can read

ProjectServiceRemoveNamespaceRequest

request to remove a namespace from a project

Field Type Description
name string the name of the project
namespace string the name of the namespace to remove

ProjectServiceRemoveNamespaceResponse

response after removing a namespace from a project

This message has no fields.

ProjectServiceUpdateRequest

request to update a project

Field Type Description
project Project the project to update, identified by its name, carrying the new values of the fields to change
update_mask google.protobuf.FieldMask the fields to change - only description can be. See Update.

ProjectServiceUpdateResponse

response for updating a project

Field Type Description
project Project the updated project

Pseudonym

the pseudonym entity

Field Type Description
meta Meta metadata about the pseudonym
namespace string the namespace of the pseudonym
original_value optional string the original value that was pseudonymized. Set in every response that is about a specific original value the caller named or is entitled to see - Create, Append, Import, Resolve and the reverse lookup (Get). List never sets it, by design.
pseudonym_value string the pseudonym created for the original value
sequence_number int64 this pseudonym's position (starting at 0) among possibly multiple pseudonyms stored for the same original value in a multi-psn namespace. Always 0 otherwise.

PseudonymListPaginationToken

contents of the PseudonymServiceList pagination token: the position of the last-seen pseudonym in the (created_at desc, original_value desc) ordering, used for keyset/seek pagination rather than an offset - this scales to hundreds of millions of rows per namespace, where an offset-based token would degrade linearly with page depth.

Field Type Description
created_at google.protobuf.Timestamp created_at of the last-seen pseudonym in the previous page
original_value string original_value of the last-seen pseudonym in the previous page - tie-breaker for pseudonyms sharing the same created_at
sequence_number int64 sequence_number of the last-seen pseudonym in the previous page - final tie-breaker for pseudonyms sharing the same (created_at, original_value), which a multi-psn namespace (see Namespace.allows_multiple_pseudonyms) can otherwise produce

PseudonymServiceAppendRequest

request to store one additional pseudonym for an original value

Field Type Description
namespace string the namespace to append the pseudonym in. Must allow multiple pseudonyms per original value.
original_value string the original value to store another pseudonym for. If none is stored for it yet, the appended pseudonym is its first (sequence_number 0).
request_id string an optional UUID identifying this request across retries, following AIP-155 (https://google.aip.dev/155). Generate a new one for every distinct append and send the same one only when retrying it: a call whose request_id was already used successfully in this namespace stores nothing and returns the pseudonym the earlier call stored. Reusing it for a different original_value is an INVALID_ARGUMENT, as is a value that isn't a UUID. Without a request_id every call appends.

PseudonymServiceAppendResponse

response for appending a pseudonym

Field Type Description
pseudonym Pseudonym the pseudonym this call stored - only the new one, not the full set. Its sequence_number is one past the highest already stored for the original value. For a retried request_id, the pseudonym the original call stored.

PseudonymServiceCreateRequest

request to pseudonymize and store a given value

Field Type Description
namespace string the namespace in which the pseudonym should be created
original_value string the original value to be pseudonymized
count optional int64 how many distinct pseudonyms to store for this original value. Only valid to set above 1 when the target namespace has allows_multiple_pseudonyms set - unset (or 1) preserves today's single-pseudonym behavior for every other namespace. If fewer than this many pseudonyms already exist for the original value, exactly the missing ones are generated and added; if this many or more already exist, the existing set is returned unchanged. At most 10000.

PseudonymServiceCreateResponse

response for creating a pseudonym entity

Field Type Description
pseudonym Pseudonym the created pseudonym. For a multi-psn namespace this is always the first (sequence_number 0) pseudonym of the full set below, kept for backwards compatibility with callers that only read this field.
pseudonyms repeated Pseudonym every pseudonym stored for the requested original value after this call - length 1 unless the target namespace allows multiple pseudonyms per original value.

PseudonymServiceGetRequest

message to fetch details for a given pseudonym

Field Type Description
namespace string the namespace the pseudonym is a part of
pseudonym_value string the actual pseudonym

PseudonymServiceGetResponse

response for getting a pseudonym entity

Field Type Description
pseudonym Pseudonym the found pseudonym

PseudonymServiceImportRequest

request to store an externally created pseudonym for an original value

Field Type Description
namespace string the namespace to store the pseudonym in. Must use PSEUDONYM_GENERATION_METHOD_EXTERNAL.
original_value string the original value the pseudonym was created for. Must not be blank, and must match the namespace's original value validation regex, if it has one.
pseudonym_value string the pseudonym to store, exactly as given - the namespace's prefix and suffix are not applied. Must not be blank.

PseudonymServiceImportResponse

response for importing an external pseudonym

Field Type Description
pseudonym Pseudonym the stored pseudonym - the one this call created, or the identical one that was already there.

PseudonymServiceListRequest

request to list all pseudonyms in a namespace

Field Type Description
namespace string the namespace to list the containing pseudonyms of
page_size int32 specify the maximum number of results to be returned by the server. If the page_size is 0, the server will decide the number of results to be returned.
page_token string an opaque pagination token. Use this field to request a specific page of the list results.
include_total_size bool include the total number of pseudonyms in the namespace as part of the response

PseudonymServiceListResponse

response listing all pseudonyms in a namespace

Field Type Description
namespace string the namespace containing the pseudonyms
total_size optional int64 if include_total_size is set to true in the request, this is the total number of pseudonyms in the namespace
next_page_token string an opaque pagination token. Use this field to request the next page of results by setting the request's page_token to this value.
pseudonyms repeated Pseudonym list of pseudonyms in the namespace

PseudonymServiceResolveRequest

request to resolve the pseudonym already stored for an original value

Field Type Description
namespace string the namespace to look the original value up in
original_value string the original value whose pseudonym is wanted. Nothing is stored for it - if this namespace holds no pseudonym for it, the call returns NOT_FOUND rather than creating one.

PseudonymServiceResolveResponse

response for resolving an original value's existing pseudonym

Field Type Description
pseudonym Pseudonym the pseudonym found. For a multi-psn namespace this is the first (sequence_number 0) pseudonym of the full set below, mirroring PseudonymServiceCreateResponse.
pseudonyms repeated Pseudonym every pseudonym stored for the requested original value - length 1 unless the namespace allows multiple pseudonyms per original value. Never empty: an original value with none returns NOT_FOUND instead.

Enums

ParentValidationMode

how original values in a child namespace are validated against its parent namespace

Value Number Description
PARENT_VALIDATION_MODE_UNSPECIFIED 0 unspecified performs no validation against the parent namespace
PARENT_VALIDATION_MODE_ENSURE_EXISTS 1 the original value must already exist as a pseudonym value in the parent namespace, otherwise the request is rejected

PseudonymGenerationMethod

method used to generate the pseudonyms in the namespace

Value Number Description
PSEUDONYM_GENERATION_METHOD_UNSPECIFIED 0 unspecified defaults to PSEUDONYM_GENERATION_METHOD_SECURE_RANDOM_BASE64URL_ENCODED
PSEUDONYM_GENERATION_METHOD_SECURE_RANDOM_BASE64URL_ENCODED 1 generate pseudonyms in the following format: <hashed machine name><ms ticks since system start><cryptographically-secure pseudonym_length random bytes> where: <hashed machine name>: the first 4 bytes of the SHA256-hashed machine name (host name). <ms ticks since system start>: the 4 least significant bytes of the 64-bit millisecond tick count since the system started. <cryptographically-secure pseudonym_length random bytes>: pseudonym_length random bytes. all bytes are concatenated and encoded using URL-safe BASE64.
PSEUDONYM_GENERATION_METHOD_UUID4 3 The method creates a Version 4 Universally Unique Identifier (UUID) as described in RFC 4122, Sec. 4.4.
PSEUDONYM_GENERATION_METHOD_UUID7 4 The method creates a Version 7 Universally Unique Identifier (UUID) as described in RFC 9562.
PSEUDONYM_GENERATION_METHOD_FULL_RANDOM_HEX_ENCODED 5 A fully cryptographically-safe randomly generated string encoded as hex.
PSEUDONYM_GENERATION_METHOD_FULL_RANDOM_BASE62_ENCODED 6 A fully cryptographically-safe randomly generated string encoded as Base62.
PSEUDONYM_GENERATION_METHOD_FULL_RANDOM_BASE32_ENCODED 7 A fully cryptographically-safe randomly generated string encoded as Base32, using the alphabet defined in RFC 4648, section 6 (https://datatracker.ietf.org/doc/html/rfc4648#section-6).
PSEUDONYM_GENERATION_METHOD_VOPRF 8 Derived from the original value by a verifiable oblivious pseudorandom function (RFC 9497), evaluated by a separate key-holding service that never sees the value.

Unlike every other method here this one is deterministic: the same original value always yields the same pseudonym, which is what lets two deployments holding the same key agree on pseudonyms without ever exchanging the values behind them. The consequences are that a namespace using it cannot allow multiple pseudonyms per original value (there is only one pseudonym to be had), and that its pseudonym length is fixed by the VOPRF client's configuration rather than chosen per namespace.

Requires a configured VOPRF server; namespace creation fails with FAILED_PRECONDITION otherwise.
PSEUDONYM_GENERATION_METHOD_EXTERNAL 9 The namespace generates nothing: its pseudonyms are created outside vfps (by a third party) and stored verbatim through PseudonymService.Import, which is the only RPC that writes to such a namespace - Create and Append return FAILED_PRECONDITION, so a pseudonym vfps generated can never end up next to an external one. Resolve, Get and List work as usual.

pseudonym_length, pseudonym_prefix and pseudonym_suffix are ignored: imported values are stored exactly as given. allows_multiple_pseudonyms is honored - without it a second, different pseudonym for the same original value is rejected.