Piipe Developer Platform

The integration model

One customer reference across two clear responsibilities.

Keep business relationships and non-identifying facts in your application. Store direct identity in Piipe under the same application-owned customer reference.

Call Piipe from trusted server workflows

Keep application credentials out of browser code, use finite timeouts and request only the identity fields each workflow needs.

01Choose a random customer ID

Use a non-identifying value for application joins and Piipe requests.

02Store named identity fields

Send the direct identifiers your application no longer needs to hold.

03Retrieve the minimum

Request only the approved fields at the moment an authorised workflow needs them.

Quickstart

Connect a trusted server workflow.

Your application profile binds one organisation, application and purpose to a protected session key. Keep the complete profile in your server-side secret manager and let the Piipe SDK create and verify every request envelope.

Python server setup

import os
from piipe import EnvelopeHttpsTransport, PiipeApplicationClient, PiipeConfig

key = bytes.fromhex(os.environ["PIIPE_SESSION_KEY_HEX"])
epoch = int(os.environ["PIIPE_BOOT_EPOCH"], 0)
transport = EnvelopeHttpsTransport(
    "api.piipe.io", session_key=key, boot_epoch=epoch
)
client = PiipeApplicationClient.from_transport(
    transport,
    PiipeConfig(
        tenant_id=int(os.environ["PIIPE_TENANT_SLOT"]),
        application_id=int(os.environ["PIIPE_APP_ID"]),
        purpose_code=int(os.environ["PIIPE_PURPOSE_CODE"]),
        session_id=int(os.environ["PIIPE_SESSION_ID"], 0),
        boot_epoch=epoch,
        packet_auth_key=key,
        initial_request_id=int(os.environ["PIIPE_REQUEST_ID"], 0),
        initial_sequence=int(os.environ["PIIPE_SEQUENCE"], 0),
    ),
)

1
Protect the application profile
Load it only inside the trusted server process that needs PII access.
2
Create the encrypted transport
The SDK seals requests for Piipe and verifies every response before returning it.
3
Use explicit fields
Prefer email,phone over retrieving a complete identity collection.
4
Advance requests once
Preserve the issued counters and reconcile uncertain mutations before retrying.

Secure PII operations

A focused API for the identity lifecycle.

SDK operation	Purpose
`search_subject`	Find an exact customer reference without returning identity fields.
`write_subject_field_record`	Store named identity fields for a customer reference.
`read_subject_fields`	Retrieve only the explicitly requested fields.
`update_field_record`	Replace named field values as one logical change.
`delete_subject_record`	Remove the live identity record from normal access.
`ping`	Verify an authenticated service exchange without moving PII.

Store identity

saved = client.write_subject_field_record(
    "customer_12345",
    {
        "name": "Example Person",
        "email": "person@example.com",
    },
    subject_type="customer_id",
)

Retrieve selected fields

identity = client.read_subject_fields(
    "customer_12345",
    ["name", "email"],
    subject_type="customer_id",
)

Data model

Move direct identity. Keep useful business context.

PROTECT WITH PIIPEDirect identity

NameLegal, full or preferred name
Email and phoneDirect contact details
AddressStreet or postal address
Date of birthExact birth date
Organisation-defined fieldsOther direct or sensitive identity values

KEEP WITH YOUR APPLICATIONBusiness relationship

Random customer IDPrimary key and join target
Account statePlan, status and permissions
CommerceOrders, products and totals
Product activityEvents and feature use
Workflow stateNon-identifying operational context

Named identity fieldsCommon names plus organisation-defined fields

Flexible

nameemailphoneaddressdobdocument

Treat one customer’s named fields as a logical identity collection. Design request sizes around the limits published for your plan and application.

Reliability and privacy

Make retries deliberate.

01Use finite timeouts

Bound every request and treat a timeout as an unknown outcome until reconciled.

02Do not log sensitive values

Keep credentials, sessions and identity fields out of application logs and error trackers.

03Reconcile uncertain writes

Do not blindly repeat a timed-out store, update or delete request. Check the customer reference and request outcome first.

SERVER SIDE ONLY

Keep application credentials and Piipe sessions out of browser code, mobile applications, source repositories and analytics events.

API contract

Use the machine-readable definition.

The OpenAPI 3.1 document defines the fixed authenticated-envelope exchange used by the Piipe v2 SDK.

Open the API contract Create your workspace