APPROVED APPLICATION FILES

Use HTTP Basic for the confidential app plus its owner-scoped JSON access token. API-only owner setup and separate exact-file decryption approval are documented in the complete workflow.

Data Vault commands, payloads and five-owner mainnet acceptance

POST

Protected data vault

Use owner approved application encrypted files

/api/v2/data-vault/files

AUTHENTICATIONBearer token · vault:files:upload or vault:files:read, operation dependentService ownervault-serviceContract sourceOpenAPISTATUSProduction listed

Purpose and usage

What this endpoint does

Upload and retrieve encrypted files created through this exact confidential application and consenting owner; obtain backend decryption only after separate exact-file approval.

When to use it

Connect a registered application to each user's own protected personal Vault through the documented API-only flow.

OUTCOME · prepare → encrypt → upload/commit → request exact-file review → owner approval → retrieve/decrypt → revoke or expire

What changes

Stable prepare/upload/commit operations create encrypted objects and commitment-only native evidence; request-decryption creates a pending owner review, not access or approval.

WHY IT MATTERS

Separates each app-owner file namespace.
Allows exact-file approved processing without exposing owner root keys.
Provides independently verifiable commitment evidence and bounded revocable access.

ISOLATION + AUTHORITY

App Basic, scoped owner connection and selected-file recipient consent are distinct. No general Vault adoption, other-owner access, automatic Cortex knowledge import, Messaging archival or financial authority.

BEFORE YOU CALL

Vault-enabled confidential app with its registered recipient public key.
Current explicit owner consent for the requested file scopes, native authority and protected Vault.
Separate owner-device approval of the exact file, manifest, recipient, purpose and expiry before backend decryption.

WHAT TO DO NEXT

Complete the API-only guide's owner setup and explicit app authorization.
Request and review selected-file decryption separately.
Verify new proof finality and exercise revocation before production registration.

AGENT GUIDANCE

Keep native sessions, owner passwords/MFA and private protection keys off the partner backend.
Persist original request/file IDs and exact encrypted bytes across uncertain retries.
A new pending request never clears revocation. Renewals cannot revive withdrawn app or native owner authority.
Follow /api-reference/v2/guides/data-vault; no browser or MPC wallet is required for the verified flow.

Contract reference

Use the deployed OpenAPI for exact parameters, schemas and security requirements. The tables below provide integration guidance.

Open this operation in OpenAPI

Request and response

Make the request

Examples illustrate integration intent; the referenced OpenAPI operation and component schemas define the executable shape.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

AuthorizationheaderRequired

HTTP BasicRegistered confidential application authentication. File operations use the owner app-scoped access_token in JSON; refresh-connection instead uses only its separate app-scoped renewal capability.EXAMPLEBasic <registered-app-client-and-secret>

X-Request-IDheaderOptional

stringOptional caller correlation identifier. The gateway emits the effective value on the response.

REQUEST

JSON body example

{
  "operation": "refresh-connection",
  "refresh_token": "example-refresh-token",
  "request_id": "01K4A7M4N8Y2Q6R9T3V5W7X1ZB"
}

STABLE ERROR CODES

Branch on the code, then follow the recovery action

These codes are published by the authoritative gateway contract for this endpoint. Treat message as safe diagnostic text; integrations should branch on code and HTTP status.

STATUSCODEMEANING

401invalid_credentialsThe bearer credential is missing, expired, or invalid.

403insufficient_scopeThe principal lacks owner-scoped Data Vault read authority.

404data_vault_object_not_foundThe object does not exist in the authenticated workspace.

422invalid_data_vault_objectThe object identifier is invalid.

422data_vault_request_rejectedOwner or workspace policy rejected the Data Vault request.

503data_vault_unavailableAuthoritative Data Vault metadata is temporarily unavailable.

RESPONSES

Status and payload examples

200Validated encrypted storage receipt or application-scoped inventoryMutation completed · JSON RESPONSE+

"example-value"

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then complete the API-only guide's owner setup and explicit app authorization.
RETRY SAFETY: Do not repeat a successful mutation merely to confirm it. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Persist returned identifiers, versions, commitments, and receipts. Refresh vault metadata, classification, object commitment, retention version, grant state, and audit record; never infer access to encrypted payload bytes from metadata.

400The request syntax, required metadata, or JSON body is malformed.Request must change · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Refresh vault metadata, classification, object commitment, retention version, grant state, and audit record; never infer access to encrypted payload bytes from metadata.
ESCALATE WHEN: Escalate when ownership, grant, retention, classification, or commitment evidence cannot be reconciled without disclosing protected data.

401Application authentication or owner session expired.Authentication required · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "The bearer credential is missing, expired, or invalid."
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Discard the rejected credential, complete the documented authentication or reassertion flow, and rebuild any request signature with fresh timestamps and nonces.
RETRY SAFETY: Retry only with a newly valid credential and fresh replay-protection values. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Assume the outcome is unknown only when the connection failed after transmission; otherwise authentication failed before domain work. Refresh vault metadata, classification, object commitment, retention version, grant state, and audit record; never infer access to encrypted payload bytes from metadata.
ESCALATE WHEN: Escalate when ownership, grant, retention, classification, or commitment evidence cannot be reconciled without disclosing protected data.

403Current owner consent or authority is missing.Authority or policy denied · JSON RESPONSE+

{
  "code": "insufficient_scope",
  "message": "The principal lacks owner-scoped Data Vault read authority."
}

INTEGRATION DECISIONinsufficient_scope

CALLER ACTION: Verify the exact scope, tenant or workspace membership, owner boundary, step-up purpose, feature policy, and resource eligibility. Never broaden authority automatically.
RETRY SAFETY: Do not retry until the missing authority or policy condition has been deliberately resolved with least privilege.
STATE RECONCILIATION: Confirm the caller and resource resolve to the same authority boundary for owner-scoped vault metadata, data classifications, commitments, retention state, grants, and audit evidence.
ESCALATE WHEN: Escalate when ownership, grant, retention, classification, or commitment evidence cannot be reconciled without disclosing protected data.

404File is unavailable to this app and owner.Resource not visible · JSON RESPONSE+

{
  "code": "data_vault_object_not_found",
  "message": "The object does not exist in the authenticated workspace."
}

INTEGRATION DECISIONdata_vault_object_not_found

CALLER ACTION: Verify the canonical identifier and authenticated owner boundary. A 404 may intentionally conceal a resource outside the caller's authority.
RETRY SAFETY: Do not retry the unchanged identifier repeatedly. Refresh the relevant collection or lookup before choosing another identifier.
STATE RECONCILIATION: Refresh vault metadata, classification, object commitment, retention version, grant state, and audit record; never infer access to encrypted payload bytes from metadata.
ESCALATE WHEN: Escalate when ownership, grant, retention, classification, or commitment evidence cannot be reconciled without disclosing protected data.

409Upload state or immutable retry changed.State reconciliation required · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Stop the mutation sequence and fetch the latest authoritative resource, lifecycle state, version, ETag, reservation, or existing idempotency result.
RETRY SAFETY: Retry only after reconciling the conflict. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Refresh vault metadata, classification, object commitment, retention version, grant state, and audit record; never infer access to encrypted payload bytes from metadata.
ESCALATE WHEN: Escalate when ownership, grant, retention, classification, or commitment evidence cannot be reconciled without disclosing protected data.

413Ciphertext transport size exceeded.Request must change · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Refresh vault metadata, classification, object commitment, retention version, grant state, and audit record; never infer access to encrypted payload bytes from metadata.
ESCALATE WHEN: Escalate when ownership, grant, retention, classification, or commitment evidence cannot be reconciled without disclosing protected data.

429The caller exceeded an enforced request or resource limit.Caller must slow down · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Honor Retry-After when present, reduce concurrency, and apply bounded exponential backoff with jitter.
RETRY SAFETY: Retry after the server-provided delay. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Refresh vault metadata, classification, object commitment, retention version, grant state, and audit record; never infer access to encrypted payload bytes from metadata.
ESCALATE WHEN: Escalate when ownership, grant, retention, classification, or commitment evidence cannot be reconciled without disclosing protected data.

503Storage or identity authority unavailable.Dependency unavailable or outcome uncertain · JSON RESPONSE+

{
  "code": "data_vault_unavailable",
  "message": "Authoritative Data Vault metadata is temporarily unavailable."
}

INTEGRATION DECISIONdata_vault_unavailable

CALLER ACTION: Preserve the exact request and treat the outcome as uncertain until authoritative state proves whether it committed.
RETRY SAFETY: Reconcile before retrying. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt. Use bounded backoff with jitter.
STATE RECONCILIATION: Refresh vault metadata, classification, object commitment, retention version, grant state, and audit record; never infer access to encrypted payload bytes from metadata.
ESCALATE WHEN: Escalate when ownership, grant, retention, classification, or commitment evidence cannot be reconciled without disclosing protected data.

OPERATIONAL NOTES

Security and lifecycle guarantees

Server-to-server only. Authenticate the registered confidential application using HTTP Basic, and supply the owner's current Hybrid ID OAuth access_token. The owner must explicitly approve vault:files:upload and/or vault:files:read. prepare-upload allocates a stable file ID before local encryption. register binds its immutable encrypted manifest, put-chunk sends a ciphertext chunk, commit verifies completion, read/read-chunk retrieve ciphertext. list exposes only files created through this exact application and owner connection. Request context and vault IDs are derived by Hybrid ID; never send a password, private key, general account credential or caller-selected vault. Revocation and session expiry are checked on every request. Exact encrypted retries reuse the original request/file identifiers. refresh-connection renews a separately approved owner/API file connection using only its app-scoped renewal capability and current confidential app authentication; native credentials are never sent to the partner. It cannot renew expired/revoked native authority, consent or grants. request-decryption asks for separate owner approval of this exact file, recipient key, purpose and expiry; decryption-status reports the decision and releases a wrapped file key only while approved. OAuth read consent does not itself permit backend decryption. Revocation, expiry, recipient rotation and changed owner consent stop future file retrieval; already decrypted information cannot be recalled. No wallet or spending authority is granted.
prepare-upload accepts a stable request_id; exact encrypted retries reuse the allocated object_id and immutable registration. No Idempotency-Key header is used.
Ciphertext retrieval does not disclose the owner private key or grant plaintext processing authority.
Selected-file decryption requires separate owner approval of exact file, manifest, app, recipient key, purpose and expiry; ciphertext-read consent alone is insufficient.
The owner-device API supports API-only signup/protection/consent. It never sends native credentials or owner keys to the partner backend.
Scoped renewal is bounded by the original native session and approval window; it cannot restore withdrawn consent.
The tables and examples are derived from the current gateway source OpenAPI. Re-fetch the deployed OpenAPI before execution; deployment status is shown separately on this page.
Only parameters present in the OpenAPI operation are accepted; undocumented query keys fail closed with HTTP 422.

Reference version and availability details

This route is implemented in canonical gateway source and appears in the production OpenAPI snapshot observed 2026-10-02T23:27:55.510Z. Authentication, tenant, feature, venue, and market policy still apply.

Verify the exact production OpenAPI operation Return to the V2 directory