← Back to API reference

Understanding Psono's encryption layers

This OpenAPI 3.1 reference covers the canonical API operations in Community and Enterprise, including administration, file-server coordination, SAML, OIDC, SCIM, and gateway communication. The checked-in YAML files are maintained independently of Django; the documentation build does not import or introspect either server.

The route inventory and excluded compatibility aliases are stored in api/openapi/routes.json and checked during the build. Generic framework OPTIONS/HEAD behavior is inherited from the corresponding view; it is not listed as duplicate operations. Framework HTML login pages under /api-auth/, debug-only schema/coverage pages, and static files are outside this application API reference.

Community and Enterprise availability

Every operation declares x-psono-editions: [CE, EE] or [EE]. The build uses this metadata to create separate importable specifications. Enterprise includes all shared operations documented here, plus Enterprise-only administration, SSO, provisioning, and gateway operations. Shared operations can have different payloads or behavior in Enterprise; the edition switch selects the appropriate contract.

Optional routes also depend on configuration:

API area Required configuration
Administration MANAGEMENT_ENABLED
File-server coordination FILESERVER_HANDLER_ENABLED
Gateway GATEWAY_HANDLER_ENABLED (Enterprise)
SAML SAML enabled in AUTHENTICATION_METHODS and SAML_CONFIGURATIONS
OpenID Connect OIDC enabled in AUTHENTICATION_METHODS and OIDC_CONFIGURATIONS
SCIM SCIM_CONFIGURATIONS (Enterprise)
Management commands MANAGEMENT_COMMAND_ACCESS_KEY and ALLOWED_MANAGEMENT_COMMANDS

The reference preserves actual path spelling, casing, and trailing slashes, including /admin/webautn/. Compatibility routes with unused path identifiers are excluded. Body-ID writes use the collection URL and include the identifier in the request payload. Detail reads and SCIM updates retain path identifiers where the handler uses them to select the resource.

Wire format versus logical payload

An ordinary session request follows these steps:

Secret JSON
    │ vault encryption with the secret's key
    ▼
Logical request: { data, data_nonce, link_id, ... }
    │ session encryption with the session secret key
    ▼
HTTP body: { text, nonce }
    │ HTTPS
    ▼
Psono server

The standard OpenAPI request and response schemas describe the HTTP body. The additional “Payload before transport encryption” and “Payload after transport decryption” sections describe the logical JSON. Their schemas are kept as reusable components and linked through x-psono-encryption.

Never send those logical payloads directly to session-encrypted endpoints. The GET /secret/{secret_id}/ operation needs no request body, but its successful response is still session-encrypted.

Session SecretBox profile

Decrypt the response with the same session key, verify authentication, decode UTF-8, and parse JSON. The resulting data field can still contain vault ciphertext.

Example helper using Python and PyNaCl:

import json
import nacl.encoding
import nacl.secret
import nacl.utils

def encrypt_payload(payload, session_key_hex):
    box = nacl.secret.SecretBox(
        session_key_hex, encoder=nacl.encoding.HexEncoder
    )
    nonce = nacl.utils.random(nacl.secret.SecretBox.NONCE_SIZE)
    plaintext = json.dumps(payload).encode("utf-8")
    encrypted = box.encrypt(plaintext, nonce)
    return {"text": encrypted.ciphertext.hex(), "nonce": nonce.hex()}

def decrypt_payload(envelope, session_key_hex):
    box = nacl.secret.SecretBox(
        session_key_hex, encoder=nacl.encoding.HexEncoder
    )
    plaintext = box.decrypt(
        bytes.fromhex(envelope["text"]), bytes.fromhex(envelope["nonce"])
    )
    return json.loads(plaintext.decode("utf-8"))

Ciphertext examples in the reference are illustrative placeholders, not decryptable test vectors. Real ciphertext must be generated for the current session and request.

Session authentication

Use Authorization: Token <session-token>, including the literal Token prefix. This is not Bearer authentication. The session must be activated and have the appropriate read or write permission. Multifactor challenge and token-activation operations accept the inactive token returned during password login.

Signed server information

GET /info/ returns the server configuration as a JSON-encoded info string with an Ed25519 signature and verify_key. Verify the detached signature over the exact UTF-8 info string before parsing it. Re-serializing the JSON changes the signed bytes. Establish trust in the verification key separately; a response's own key alone does not establish server identity.

Password login

  1. Read and verify /info/ to obtain trusted server cryptographic information.
  2. POST /authentication/prelogin/ with the username to discover its hashing algorithm and parameters. Derive the authentication key locally.
  3. Generate a temporary client Curve25519 key pair. Encrypt the LoginInfoPayload JSON using NaCl Box with the temporary private key and the server public key; send the temporary public key, ciphertext, and nonce to POST /authentication/login/.
  4. Decrypt the response login_info with the same keys. Its session_secret_key is separately wrapped using the returned session_public_key and the temporary client key. user_validator is separately wrapped for the user's public key.
  5. Use the resulting session secret key for transport encryption. Complete the challenges in required_multifactors, then call POST /authentication/activate-token/ with encrypted proof of possession of the decrypted user validator.

For activation, SecretBox-encrypt the raw UTF-8 user-validator string with the session secret key; do not JSON-encode that string. Send the ciphertext and its separate nonce as verification and verification_nonce, then encrypt the complete logical activation request in the normal session {text, nonce} envelope.

The endpoint schemas describe both outer envelopes and the JSON inside encrypted fields. A login envelope is not interchangeable with a session {text, nonce} body.

For a complete existing session-establishment example, see API-key usage with a session.

API-key session login

POST /api-key/login/ takes a signed JSON string in info. Sign its exact UTF-8 bytes with the API key's Ed25519 signing key. That JSON contains the API-key ID and a temporary Curve25519 session_public_key, plus optional session/device settings. The signing key and temporary encryption key pair are different keys.

Verify login_info_signature over the returned hex login_info string. Decrypt it using the temporary client private key and the response's server_session_public_key. The enclosed session_secret_key is ready for session transport encryption, and the returned token is already active. Keys restricted to individual secrets use the sessionless interface instead.

Device approval

Create a five-minute code with POST /device-code/, then compare its independent user_code on an authenticated approving client. The approving client reads and claims /device-code/{device_code}/claim/ using a normal user session; API-key sessions cannot approve codes. The initiating device retrieves the result from POST /device-code/{device_code}/token/. Decrypt its boxed_payload with the initiating device's private key and the server public key returned at creation. A successful retrieval consumes the code and establishes a new active session.

Recovery and emergency exchanges

The first POST /password/ or POST /emergency-login/ obtains the recovery or emergency material and verifier public key. For the subsequent PUT, encrypt update_data with the user's private key and that verifier public key. Recovery replaces the wrapped user keys and authentication key; emergency access instead returns a boxed active session after the configured activation delay. Their logical update_data schemas are documented with each operation.

Sessionless API-key access

POST /api-key-access/secret/ takes an ordinary JSON body and does not require a session envelope. Its two response modes are selected by the request:

  1. Local decryption: omit api_key_secret_key. Unwrap the returned secret_key using your API-key symmetric secret and secret_key_nonce; then use that key and data_nonce to decrypt data.
  2. Remote decryption: supply api_key_secret_key, with allow_insecure_access enabled on the API key. The response is the stored JSON or the value selected by the dot-separated json_filter.

These responses are not session-encrypted. HTTPS still protects transport.

Enterprise SCIM authentication

Use Authorization: Bearer <SCIM-provider-token> and Accept: application/scim+json. This is the configured SCIM provider token, not a Psono session token. SCIM responses do not use a SecretBox envelope. The schema discovery route is case-sensitive and has no trailing slash.

SCIM resource creation/replacement uses application/scim+json. Use the standard attribute spellings such as userName, externalId, and displayName; resource serializers accept these case-insensitively. PATCH uses an Operations array with operation-specific JSON values. List operations support the documented filter, count, and startIndex query parameters; startIndex is one-based. DELETE returns HTTP 204 with no body.

Enterprise SAML and OIDC

Initiate the configured identity-provider flow and send the user to the returned provider URL. SAML delivers SAMLResponse and optional RelayState as form data to its ACS endpoint. OIDC returns code and state to the callback URL; backchannel logout separately receives a signed logout_token as form data. These browser callbacks and redirects use no session SecretBox envelope.

Exchange the resulting one-time SAML/OIDC token through /saml/login/ or /oidc/login/. The request uses the normal public-key login_info wrapper, but the response has two Box layers: decrypt login_info with the trusted server key, then decrypt its data field with the returned ephemeral server_session_public_key. The inner session details contain the session secret key, user information, and a separately wrapped user-validator challenge. Honor any returned multifactor requirements before token activation.

File-transfer and service credentials

The same {text, nonce} wire shape is used with several distinct keys:

Interface Authorization Transport key
User session Token <session-token> Session secret
Repository transfer authorization Filetransfer <transfer-id> File-transfer secret
File-server coordination Token <fileserver-id> Registered file-server session secret
Enterprise gateway coordination Token <gateway-id> Registered gateway session secret

These coordination endpoints do not themselves transfer file bytes. File creation and download authorization return a transfer ID/key; clients upload/download encrypted chunks through the selected file-server/repository endpoints. Repository upload/download operations return provider-specific URLs and form fields.

File-server tickets

The ticket supplied to file-server authorization/revocation is client-generated JSON encrypted with SecretBox using the file-transfer secret key and a separate ticket_nonce, both encoded as hex. Download tickets contain hash_checksum; upload tickets also contain chunk_position.

This ticket is nested inside the coordination request. Encrypt that outer {text, nonce} envelope with the registered file-server session key, not the file-transfer key. The authenticated file server must have access to the transfer's shard. The operation-specific ticket schemas list the logical fields.

Administration and pagination

Administration requires the corresponding capability and authorized tenant scope. Operations that require a superuser are identified explicitly. Enterprise-only creation, identity-provider mappings, policy, managed-key recovery, and gateway administration do not become available merely by assigning a Community role.

Use each operation's documented query/body location for pagination and filtering. Some older GET handlers read a JSON body; those operations are marked explicitly. Ordinary administration page parameters are zero-based at the API boundary; SCIM startIndex is one-based. A count value can be null when optional pagination is not requested.

Errors can have different envelopes

For the session endpoints documented here:

Do not decide whether to decrypt solely from the status code. Consult the operation's response schema and check for the text/nonce envelope.

Importing the specifications

Download the CE or EE YAML/JSON file from the reference header and import it into an OpenAPI-compatible tool. Each file is self-contained, including logical schemas.

Standard tools understand the wire schemas. They do not automatically implement the custom x-psono-encryption metadata, session establishment, or vault decryption. The reference's generated curl examples likewise describe the wire request; use the helper above or an existing Psono client for encryption.