{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/api-reference/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["api-container","api-content","endpoint","api-examples","tabs","tab","code-group"]},"redocly_category":"API Reference","searchWeight":120,"type":"markdown"},"seo":{"title":"Create an encrypted area","description":"Complete API reference and documentation for Freddy AI-powered backend system by Aitronos","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"create-an-encrypted-area","__idx":0},"children":["Create an encrypted area"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Encrypts a piece of text or an uploaded file end-to-end and returns the new area's id. Use it"," ","to share a credential, an API key, a private note, or a sensitive file: choose who it is for,"," ","set the optional controls, and Aitronos either delivers it for you or hands you a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["secure"," ","link"]}," to forward yourself."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Aitronos never holds a key that can read the area."]}," For a secure link, the decryption key"," ","travels in the link's URL fragment (the part after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["#"]},"), which browsers never send to a"," ","server — so the key never reaches Aitronos. Storage holds ciphertext only."]}]},{"$$mdtype":"Tag","name":"ApiContainer","attributes":{},"children":[{"$$mdtype":"Tag","name":"ApiContent","attributes":{},"children":[{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"POST","path":"https://api.aitronos.com/v1/encrypted-areas"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Requires authentication (bearer token or API key). The authenticated caller is the sender, so"," ","there is no separate approval step. Creates are limited to 30 per minute per user; beyond that"," ","the endpoint answers ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retry_after"]}," in seconds."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Encrypted areas are part of Conversations."]}," Where Conversations is enabled for your account,"," ","encrypted areas are enabled with it and this endpoint works; where Conversations is switched"," ","off, the endpoint answers ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},". There is nothing extra to turn on."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"three-rules-to-read-before-you-call-this","__idx":1},"children":["Three rules to read before you call this"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The secure link is returned exactly once and can never be re-issued."]}," The key inside it is"," ","never stored, so nobody — including Aitronos — can produce the link again. If your client"," ","loses the response body, the area is unrecoverable and you must create a new one. Capture"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secure_link"]}," the moment you receive it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secure_link"]}," is returned only when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link"]},"."]}," Every other audience is"," ","delivered for you, so the response deliberately withholds the key-bearing URL."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["This endpoint is not idempotent."]}," Repeating the same request creates a second, independent"," ","area with its own key — there is no de-duplication. Retry only when you know the first call"," ","did not return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"controls-and-their-defaults","__idx":2},"children":["Controls and their defaults"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Control"},"children":["Control"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Default"},"children":["Default"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(no default — required)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Selects the security model."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["none"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional. Share it with the recipient yourself, over a different channel."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["burn_after_read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["off"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional. The area self-destructs after the first successful open."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiry"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1w"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The area expires after 7 days unless you choose otherwise."]}," Pick ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["never"]}," explicitly if it should never expire."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["burn_after_read"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiry"]}," apply to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["every"]}," audience — they are enforced by the server on"," ","both the secure-link and the identity-sealed path."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password"]}," applies only to the secure-link audiences. It feeds the key derivation, and an"," ","identity-sealed area has nowhere to carry it, so a password sent with an area that gets sealed"," ","to another Aitronos user's identity is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["dropped"]},": the response reports"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password_required: false"]}," and names it in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["controls_not_applied"]},". Read that list rather than"," ","inferring the drop from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["crypto_mode"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"body-parameters","__idx":3},"children":["Body parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#ef4444 !important","fontWeight":"600 !important","fontStyle":"normal !important"}},"children":["required"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Who the area is for. One of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["imessage"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["slack"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["teams"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link"]},"."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]}," seals the area to another Aitronos user's identity in your organization — the strongest"," ","option, because a forwarded copy stays sealed to them. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}," and the four messaging values"," ","send a secure link over that channel. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link"]}," creates a shareable secure link with no named"," ","recipient and returns it to you."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Exactly one recipient field must be supplied, and it must be the one that matches the audience."," ","Supplying a field the audience does not accept, more than one, or none at all is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"audience"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Supply exactly one of"},"children":["Supply exactly one of"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_user_id"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_email"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_contact_id"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_handle"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_contact_id"]},", or the legacy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_whatsapp"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["imessage"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["slack"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["teams"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_handle"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_contact_id"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(none — a recipient field is rejected)"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_user_id"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Required when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]},": the Aitronos user id of the recipient, who must be in the"," ","same organization. Must be omitted for every other audience. Max 255 characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_email"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Required when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},", unless you supply ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_contact_id"]}," instead: the"," ","recipient's email address. Must be omitted for every other audience. Max 320 characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_handle"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Required for the messaging audiences, unless you supply ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_contact_id"]}," instead: the"," ","recipient's address on that channel — a phone number in E.164 form (for example"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+41791234567"]},") for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["imessage"]},", a member id for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["slack"]},", a directory object id"," ","for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["teams"]},". Must be omitted for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link"]}," audiences. Max 320 characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_contact_id"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An existing contact to send to, instead of a raw address. Accepted for the four messaging"," ","audiences, and for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]}," when the send should go over that contact's email channel. Provide"," ","either this or the audience's address field, never both. Must be omitted for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link"]},"."," ","Max 255 characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_whatsapp"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Legacy alias of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_handle"]},", accepted only when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp"]},". Provide exactly"," ","one of the two, never both. Prefer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_handle"]}," for new integrations. Max 320 characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content_text"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The secret to encrypt, as inline text. Provide ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content_text"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file_ref"]},", or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["both"]}," —"," ","supplying neither is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]},". Sent together, the note is sealed alongside the file and the"," ","recipient reads it without opening the attachment."," ","Preserved byte for byte, including leading and trailing whitespace, because whitespace can be"," ","meaningful in a secret. Never stored in readable form and never written to a log. Max"," ","1,048,576 characters — use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file_ref"]}," for anything larger."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file_ref"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The id of an already-uploaded file to encrypt, which must belong to you. Provide"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content_text"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["file_ref"]},", or both. Use this rather than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content_text"]}," for anything larger"," ","than a short secret. Max 255 characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Any file type is accepted"]},", including an archive of several files — upload it through"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/encrypted-areas/upload"},"children":["the encrypted-area upload endpoint"]}," first. That"," ","endpoint takes arbitrary bytes, because a file sealed here is encrypted rather than read; the"," ","general file upload restricts types because it parses and indexes what you send it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Two size limits apply, and the lower one depends on the audience."]}," A file sealed to another"," ","Aitronos user's identity may be up to the full encrypted-area limit (100 MB). A file sent as a"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["secure link"]}," — every audience except an enrolled ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]}," recipient — may be up to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["32 MB"]},","," ","because that format carries the file inside the sealed payload. A file between the two is"," ","refused with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["413"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason: attachment_too_large_external"]}," rather than sealed into a link"," ","nobody could open."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A display label shown to the recipient alongside the sealed card. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Not secret"]}," — it is"," ","rendered into the card and, for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]}," audience, stored as part of the delivered message."," ","Never put any part of the secret here. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Encrypted area"]},". Max 120 characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A password the recipient must enter to open the area. It is folded into the key derivation on"," ","the recipient's device, is never sent to Aitronos when they open the area, and is never echoed"," ","back, delivered, or logged — share it with the recipient yourself, over a different channel."," ","Off by default. Preserved byte for byte. Max 1024 characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["burn_after_read"]}]}," boolean ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", the area self-destructs after the first successful open. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},". Must"," ","be a real boolean — a string such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"true\""]}," is rejected with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]},", because silently"," ","enabling a destructive option would be worse than an error."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiry"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["How long the area stays openable. One of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1h"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1d"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1w"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["30d"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["never"]},". ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1w"]}," —"," ","the area expires after 7 days unless you choose otherwise."]}," Choose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["never"]}," explicitly if it"," ","should not expire."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unknown fields are rejected with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," rather than ignored, so a misspelled control can never"," ","be silently dropped."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns","__idx":4},"children":["Returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]},". The response is marked ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Cache-Control: no-store"]},"."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]},", never on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]},"."]}," The two storage failures are reported differently on"," ","purpose, and only one is worth retrying. A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["503"]}," is transient: it carries a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," ","header (and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retry_after"]}," field, in seconds), and the same request will likely succeed"," ","shortly. A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["500"]}," is a configuration fault on our side that a retry can never clear — surface"," ","it and stop rather than looping. In both cases ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["nothing was created"]},": an area exists only"," ","once you have received a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}," with an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encbin_id"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encbin_id"]}]}," string · The new area's id (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encbin_"]},"-prefixed). Use it with the fetch endpoints."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience"]}]}," string · The audience the area was actually sealed for."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["crypto_mode"]}]}," string · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_bound"]}," when sealed to a recipient's identity, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external"]}," ","when opened by a key carried in the link."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["format_version"]}]}," string · The sealing format the area was written in."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fell_back_to_link"]}]}," boolean · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," when a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]}," audience could not be sealed to that"," ","user's identity (they have no key enrolled) and was sealed as a recipient-addressed secure link"," ","instead."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secure_link"]}]}," string · The complete secure link, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["including the decryption key in its URL"," ","fragment"]},". Present only for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience: \"link\""]},", returned only once, and never re-issuable."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," for every other audience. Treat it as the secret it is."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sealed_card_token"]}]}," string · The chat token that renders the sealed card for this area. It"," ","carries the area id, audience and title only — never a key and never the content."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_ref"]}]}," string · A non-secret echo of who the area was addressed to (a user id, an"," ","email address, or a channel handle). ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience: \"link\""]},"."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password_required"]}]}," boolean · Whether a password is needed to open the area, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["as resolved"]}," ","— an identity-sealed area ignores a requested password and reports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["burn_after_read"]}]}," boolean · Whether the area self-destructs on first open, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["as resolved"]},"."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_at"]}]}," string · When the area stops being openable (ISO-8601, UTC), ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["as resolved"]},", or"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," when it does not expire. This endpoint emits the numeric-offset form"," ","(",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2026-08-01T09:00:00.103591+00:00"]},"); the fetch endpoints emit the same instant in the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Z"]}," form. Parse it with a real ISO-8601 parser rather than matching on a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Z"]}," suffix."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["controls_not_applied"]}]}," array of strings · The controls you ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["asked for"]}," that this area does"," ","not carry. Empty when nothing was dropped. Today the only member is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"password\""]},", and it appears"," ","only when a password was sent and the area was sealed to a recipient's identity. It is keyed off"," ","what you requested, so an identity-sealed area created without a password returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[]"]}," rather"," ","than advertising a loss you never asked for. Show this to the sender instead of comparing"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password_required"]}," against your request — a control this list does not name ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["was"]}," applied."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivery"]}]}," object · How the area is being delivered. Six fields, below."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["security_disclosure"]}]}," object · Machine-readable security facts to show the sender. Seven"," ","fields, below."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delivery","__idx":5},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivery"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]}," string · What this request did about delivery: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returned_in_response"]}," (the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link"]}," ","audience — the link is in this response and there is no send), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["queued"]}," (the delivery was"," ","recorded and fires once the area is durably stored), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_queued"]}," (the delivery could not be"," ","recorded — the area exists but nothing will be sent). It describes the request, not the eventual"," ","send outcome."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivered"]}]}," boolean · Always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},". Delivery happens after this response is returned, so no"," ","send outcome can honestly be reported here."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}]}," string · A short human-readable note about the delivery. Never a secret."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience"]}]}," string · The audience the area was sealed for."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel"]}]}," string · The transport the area is delivered over — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["imessage"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["slack"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["teams"]}," — or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience: \"link\""]},", which has no"," ","send."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_delivery_available"]}]}," boolean · Whether this build can deliver to the chosen channel."," ","It is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["currently ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," for every supported channel"]},"; a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," would mean the area was created"," ","and sealed but will not be delivered. This describes ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["the channel's support in this build, not"," ","your environment's configuration"]}," — it will not go ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," because a mail server is down or a"," ","messaging account is disconnected. Those surface as a failed delivery afterwards, not here. The"," ","field exists so a channel that is not yet supported can be identified without a change to this"," ","response shape."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"security_disclosure","__idx":6},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["security_disclosure"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Facts only — your interface owns the wording."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["level"]}]}," string · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity_sealed"]}," when the area is sealed to a specific recipient's identity"," ","(only they can open it, even if it is forwarded), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link_key"]}," when it is opened by a key"," ","carried in the link."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key_travels_in_link"]}]}," boolean · Whether the decryption key rides in the link's URL fragment."," ","The fragment never reaches Aitronos — but anywhere the link is pasted, the key goes with it."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["anyone_with_link_can_open"]}]}," boolean · Whether possession of the link alone is enough to open"," ","the area (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," for a key-in-link area with no password)."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password_required"]}]}," boolean · Whether a password must be entered to open the area."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["burn_after_read"]}]}," boolean · Whether the area self-destructs after the first open."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_at"]}]}," string · When the area stops being openable (ISO-8601, UTC), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},". Same numeric-offset form as the top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_at"]}," above."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fell_back_to_link"]}]}," boolean · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," when a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]}," audience was sealed as a secure link"," ","because the recipient has no key enrolled — worth surfacing, because the security level is then"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link_key"]}," rather than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity_sealed"]},"."]}]},{"$$mdtype":"Tag","name":"ApiExamples","attributes":{},"children":[{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Example","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"dropdown"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"cURL","header":{"title":"cURL","controls":{"copy":{}}},"source":"curl -X POST \"https://api.aitronos.com/v1/encrypted-areas\" \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"audience\": \"link\",\n    \"content_text\": \"staging-db-password: hunter2\",\n    \"title\": \"Staging database password\",\n    \"burn_after_read\": true,\n    \"expiry\": \"1d\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python SDK","header":{"title":"Python SDK","controls":{"copy":{}}},"source":"# pip install aitronos-sdk\n#\n# The Python SDK does not expose a typed `encrypted_areas` namespace yet, so call\n# the endpoint directly with the same credential you would pass to `Aitronos(...)`\n# — an API key or a bearer token, both sent as `Authorization: Bearer <value>`.\nimport httpx\n\nAPI_KEY = \"your-api-key\"\n\narea = httpx.post(\n    \"https://api.aitronos.com/v1/encrypted-areas\",\n    headers={\"Authorization\": f\"Bearer {API_KEY}\"},\n    json={\n        \"audience\": \"link\",\n        \"content_text\": \"staging-db-password: hunter2\",\n        \"title\": \"Staging database password\",\n        \"burn_after_read\": True,\n        \"expiry\": \"1d\",\n    },\n).json()\n\n# Capture this now — the link is returned once and can never be re-issued.\nprint(area[\"secure_link\"])\nprint(area[\"security_disclosure\"][\"anyone_with_link_can_open\"])\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python","header":{"title":"Python","controls":{"copy":{}}},"source":"import requests\n\nresp = requests.post(\n    \"https://api.aitronos.com/v1/encrypted-areas\",\n    headers={\"Authorization\": f\"Bearer {ACCESS_TOKEN}\"},\n    json={\n        \"audience\": \"email\",\n        \"recipient_email\": \"colleague@example.com\",\n        \"content_text\": \"staging-db-password: hunter2\",\n        \"title\": \"Staging database password\",\n        \"password\": \"shared-out-of-band\",\n    },\n)\narea = resp.json()\n# `secure_link` is null here — the email audience is delivered for you.\nprint(area[\"encbin_id\"], area[\"delivery\"][\"status\"], area[\"delivery\"][\"channel\"])\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"JavaScript","header":{"title":"JavaScript","controls":{"copy":{}}},"source":"const resp = await fetch('https://api.aitronos.com/v1/encrypted-areas', {\n  method: 'POST',\n  headers: {\n    Authorization: `Bearer ${accessToken}`,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    audience: 'user',\n    recipient_user_id: 'usr_4f2a1c9e7b8d40a3915c2e6f8a0b1d7c',\n    content_text: 'staging-db-password: hunter2',\n    title: 'Staging database password',\n  }),\n});\nconst area = await resp.json();\n// Sealed to that user's identity: no link, and the controls resolve to off.\nconsole.log(area.security_disclosure.level, area.fell_back_to_link);\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"201 Created","header":{"title":"201 Created","controls":{"copy":{}}},"source":"{\n  \"encbin_id\": \"encbin_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"audience\": \"link\",\n  \"crypto_mode\": \"external\",\n  \"format_version\": \"v2\",\n  \"fell_back_to_link\": false,\n  \"secure_link\": \"https://chat.aitronos.com/encrypted-area/encbin_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6#3xK9uQr7...\",\n  \"sealed_card_token\": \"{{encrypted_area | id::encbin_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 | audience::link | title::Staging database password}}\",\n  \"recipient_ref\": null,\n  \"password_required\": false,\n  \"burn_after_read\": true,\n  \"expires_at\": \"2026-08-01T09:00:00.103591+00:00\",\n  \"delivery\": {\n    \"status\": \"returned_in_response\",\n    \"delivered\": false,\n    \"detail\": \"The secure link is in this response; forward it yourself.\",\n    \"audience\": \"link\",\n    \"channel\": null,\n    \"channel_delivery_available\": true\n  },\n  \"security_disclosure\": {\n    \"level\": \"link_key\",\n    \"key_travels_in_link\": true,\n    \"anyone_with_link_can_open\": true,\n    \"password_required\": false,\n    \"burn_after_read\": true,\n    \"expires_at\": \"2026-08-01T09:00:00.103591+00:00\",\n    \"fell_back_to_link\": false\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a delivered audience the shape is the same, with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secure_link"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipient_ref"]}," set, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivery.status"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["queued"]}," with the matching ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel"]},"."]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Errors","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"422 Invalid request","header":{"title":"422 Invalid request","controls":{"copy":{}}},"source":"{ \"success\": false, \"error\": { \"code\": \"VALIDATION_ERROR\", \"message\": \"Provide content_text, file_ref, or both.\", \"system_message\": \"Request validation failed\", \"type\": \"validation_error\", \"status\": 422, \"details\": { \"fields\": [ { \"field\": \"\", \"message\": \"Provide content_text, file_ref, or both.\", \"type\": \"value_error\" } ] }, \"trace_id\": \"...\", \"timestamp\": \"...\" } }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"413 File too large for a secure link","header":{"title":"413 File too large for a secure link","controls":{"copy":{}}},"source":"{ \"success\": false, \"error\": { \"code\": \"PAYLOAD_TOO_LARGE\", \"message\": \"This file is too large to send as a secure link (48 MB; the limit is 32 MB). Send it to a colleague in your organization instead, or send a smaller file.\", \"system_message\": \"This file is too large to send as a secure link (48 MB; the limit is 32 MB). Send it to a colleague in your organization instead, or send a smaller file.\", \"type\": \"validation_error\", \"status\": 413, \"details\": { \"reason\": \"attachment_too_large_external\", \"size\": 50331648, \"cap\": 33554432 }, \"trace_id\": \"...\", \"timestamp\": \"...\" } }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"403 Not enabled","header":{"title":"403 Not enabled","controls":{"copy":{}}},"source":"{ \"success\": false, \"error\": { \"code\": \"FEATURE_DISABLED\", \"message\": \"This feature is not currently enabled for your organization.\", \"system_message\": \"Encrypted areas are not enabled for this account\", \"type\": \"authorization_error\", \"status\": 403, \"details\": { \"feature\": \"encrypted_area\" }, \"trace_id\": \"...\", \"timestamp\": \"...\" } }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"429 Too many creates","header":{"title":"429 Too many creates","controls":{"copy":{}}},"source":"{ \"success\": false, \"error\": { \"code\": \"RATE_LIMIT_EXCEEDED\", \"message\": \"Too many requests. Please wait a moment and try again.\", \"system_message\": \"Rate limit exceeded\", \"type\": \"rate_limit_error\", \"status\": 429, \"details\": { \"limit\": 30, \"window_seconds\": 60, \"retry_after\": 42 }, \"retry_after\": 42, \"trace_id\": \"...\", \"timestamp\": \"...\" } }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"503 Storage temporarily unavailable","header":{"title":"503 Storage temporarily unavailable","controls":{"copy":{}}},"source":"{ \"success\": false, \"error\": { \"code\": \"SERVICE_TEMPORARILY_UNAVAILABLE\", \"message\": \"Secure storage is temporarily unavailable. Please try again in a moment.\", \"system_message\": \"Encrypted-area storage is unavailable.\", \"type\": \"service_unavailable\", \"status\": 503, \"details\": { \"reason\": \"storage_backend_unavailable\", \"retry_after\": 2 }, \"retry_after\": 2, \"trace_id\": \"...\", \"timestamp\": \"...\" } }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"500 Storage unavailable","header":{"title":"500 Storage unavailable","controls":{"copy":{}}},"source":"{ \"success\": false, \"error\": { \"code\": \"STORAGE_ERROR\", \"message\": \"Encrypted areas cannot be created right now because secure storage is not available. Retrying will not help — this needs an administrator.\", \"system_message\": \"Encrypted-area storage is unavailable.\", \"type\": \"server_error\", \"status\": 500, \"details\": { \"reason\": \"storage_backend_error\" }, \"trace_id\": \"...\", \"timestamp\": \"...\" } }\n","lang":"json"},"children":[]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-resources","__idx":7},"children":["Related resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/encrypted-areas/fetch-recipient-bound"},"children":["Fetch a recipient-bound encrypted area"]}," — and its open counterpart."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/encrypted-areas/fetch-secure-link"},"children":["Fetch a secure-link encrypted area"]}," — and its open counterpart."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/encrypted-areas/introduction"},"children":["Encrypted areas overview"]}]}]}]},"headings":[{"value":"Create an encrypted area","id":"create-an-encrypted-area","depth":1},{"value":"Three rules to read before you call this","id":"three-rules-to-read-before-you-call-this","depth":3},{"value":"Controls and their defaults","id":"controls-and-their-defaults","depth":3},{"value":"Body parameters","id":"body-parameters","depth":2},{"value":"Returns","id":"returns","depth":2},{"value":"delivery","id":"delivery","depth":3},{"value":"security_disclosure","id":"security_disclosure","depth":3},{"value":"Related resources","id":"related-resources","depth":2}],"frontmatter":{"title":"Create an encrypted area","keywords":["encrypted area","secure link","end-to-end encryption","burn after read","send a secret"],"seo":{"title":"Create an encrypted area"}},"lastModified":"2026-10-26T18:32:31.568Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/api-reference/encrypted-areas/create","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}