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
- Algorithm: NaCl SecretBox, XSalsa20-Poly1305.
- Key: the 32-byte session secret key, obtained during session establishment. It is not the token, the API-key secret, or the vault encryption key.
- Plaintext: the logical JSON serialized to UTF-8 bytes.
- Nonce: 24 random bytes. Never reuse a nonce with the same key.
text: hexadecimal ciphertext including its authentication tag, without a prepended nonce.nonce: the separate nonce, encoded as 48 hexadecimal characters.
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
- Read and verify
/info/to obtain trusted server cryptographic information. POST /authentication/prelogin/with the username to discover its hashing algorithm and parameters. Derive the authentication key locally.- Generate a temporary client Curve25519 key pair. Encrypt the
LoginInfoPayloadJSON using NaCl Box with the temporary private key and the server public key; send the temporary public key, ciphertext, and nonce toPOST /authentication/login/. - Decrypt the response
login_infowith the same keys. Itssession_secret_keyis separately wrapped using the returnedsession_public_keyand the temporary client key.user_validatoris separately wrapped for the user's public key. - Use the resulting session secret key for transport encryption. Complete the
challenges in
required_multifactors, then callPOST /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:
- Local decryption: omit
api_key_secret_key. Unwrap the returnedsecret_keyusing your API-key symmetric secret andsecret_key_nonce; then use that key anddata_nonceto decryptdata. - Remote decryption: supply
api_key_secret_key, withallow_insecure_accessenabled on the API key. The response is the stored JSON or the value selected by the dot-separatedjson_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:
- Serializer validation errors are normally session-encrypted.
- Authentication failures are plaintext HTTP 401, with the authenticator's
WWW-Authenticatechallenge (Token,Filetransfer, orBearer). - Permission errors after successful authentication can be session-encrypted.
- Maintenance/disabled-server responses, and Enterprise license-expiration responses, are plaintext HTTP 423 from middleware.
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.