Networking & API

Developer-facing terminology for the platform's networking layer and public API — covering request patterns, authentication flows, and common conventions.

API Endpoint

A specific URL path that the API exposes for a particular operation — such as creating a document, performing a search, or managing keys. Each endpoint accepts defined request parameters and returns structured responses. All public routes are versioned under /v1.

Example: GET /v1/documents/{id} is an endpoint — it accepts a document token and returns the encrypted document record.

Authentication Model

The platform uses session-based OPAQUE authentication with short-lived bearer tokens (15-minute TTL). Sessions have a bounded absolute lifetime after which a full OPAQUE handshake is required. There are no long-lived API keys — every session requires a full OPAQUE handshake. This eliminates the risk of leaked credentials granting persistent access.

Analogy: A visitor badge that expires after 15 minutes — you must re-authenticate at the front desk to get a new one.

Bearer Token

A type of access credential included in API requests (typically in the Authorization header) that grants the holder access to specific resources. The API uses bearer tokens issued after authentication to authorize subsequent requests without re-sending credentials.

Analogy: A movie ticket — whoever holds it gets in; keep it safe or someone else can use it to access your resources.

Content-Type

An HTTP header that specifies the format of the request or response body. The API uses application/json for structured data and application/octet-stream for raw encrypted content uploads.

Example: Telling a restaurant whether you want your order in a box or on a plate — application/json means structured data, application/octet-stream means raw bytes.

CORS (Cross-Origin Resource Sharing)

A browser security mechanism that controls which web origins are permitted to make API requests. The API exposes CORS headers — including X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Location, and Retry-After — to enable secure access from authorized web applications running in the browser.

Analogy: A velvet rope at a venue — only guests from the approved list get in.

gRPC

A high-performance remote procedure call framework used for internal communication between platform services. gRPC is an internal transport only — the public API surface is REST over HTTPS. Developers integrating the platform interact exclusively with the REST API.

Analogy: A compressed phone call versus reading a letter aloud — same content, much faster transmission.

HTTP Status Codes

Standardized numeric codes returned with every API response to indicate the result of the request:

• 200 OK — Request succeeded
• 201 Created — A new resource was successfully created
• 400 Bad Request — The request was malformed or missing required fields
• 401 Unauthorized — Authentication is required or the provided credentials are invalid
• 403 Forbidden — The authenticated user does not have permission for this operation
• 404 Not Found — The requested resource does not exist. On document, entity, and grant resource endpoints, the platform returns 404 for both missing resources and permission failures — an anti-oracle pattern that prevents attackers from distinguishing whether a resource exists.
• 429 Too Many Requests — Rate limit exceeded; retry after the indicated delay
• 500 Internal Server Error — An unexpected error occurred on the server

Idempotency

A property where making the same API request multiple times produces the same result as making it once. Idempotent endpoints are safe to retry after network failures without risking duplicate operations.

Analogy: Pressing an elevator button twice — it doesn't call two elevators, just responds to a single call.

Pagination

A pattern for returning large result sets in smaller, manageable chunks. The API uses page/limit pagination — requests accept page and limit parameters, and responses include total and total_pages alongside the current page of results.

Analogy: A book index split across multiple pages — you read one page, note the page number, then ask for the next page.

Problem Details

A structured error format returned on all 4xx and 5xx responses. Each error response includes a type URI identifying the error class, a human-readable title, the HTTP status code, a machine-readable code string, and an optional instance identifier for the specific occurrence. The Content-Type header is set to application/problem+json.

Example: Instead of a bare 403, the platform returns a JSON body identifying the exact error code — making programmatic error handling straightforward.

Rate Limiting

A mechanism that restricts the number of API requests a client can make within a given time window. Rate limiting protects the platform from abuse and ensures fair resource allocation across all API consumers. Current limits and window sizes are documented in the rate limiting guide.

Analogy: A bouncer who lets in at most a fixed number of people per hour regardless of how many are in the queue — fairness for everyone.

Request Signing

The practice of attaching a cryptographic signature to an API request so the server can verify that the request was not tampered with in transit and was genuinely sent by the claimed sender.

Analogy: A wax seal on a letter — proves it came from the sender and wasn't altered in transit.

REST API

An API design style where resources (documents, keys, entities) are represented as URLs, and standard HTTP methods (GET, POST, PUT, DELETE) are used to interact with them. The public API follows RESTful conventions for predictability and ease of integration.

Analogy: A filing cabinet — each drawer (resource) has a label (URL), and you use standard actions (open, add, replace, remove) on the files inside.

TLS (Transport Layer Security)

The encryption protocol that secures data in transit between your device and the platform's servers. TLS ensures that network traffic cannot be eavesdropped on or modified by third parties. All API communication requires TLS.

Analogy: An armored car for your data — the contents are protected even if the route is observed.