Symbol Docs
Features

External approvals

Let a service your organization runs decide which protected changes go live, separately from every Symbol account.

Protected Types hold every change until it is approved. By default an owner or Admin approves it. External approvals move that decision to a service your organization runs, so a compromised Symbol account, even the owner's, cannot release a change.

Symbol enforces the release boundary. You decide how to approve: manually, with an AI reviewer, with rules, or through another system.

To have AI review changes as that service, on your own infrastructure and with your own AI provider account, run Sentinel Self-hosted.

For AI review without running a service, an organization can switch on Sentinel instead. Sentinel runs inside Symbol, so it is not available while an approval service governs the organization, and it does not protect against a compromised owner account the way an approval service does.

What changes once it is on

  • Nobody with a Symbol account can approve or reject a protected change, including owners and Admins. The approve and reject controls disappear on the web and in the app, and the page says your approval service decides.
  • Members keep proposing changes, and authors can still withdraw their own.
  • Readers keep the approved version until your service decides. Pending changes stay out of listings, search, exports and AI reads.
  • Protection can no longer be turned off from a Symbol account. Your service manages it through the Approvals API.
  • Once your service decides, the change's page shows the decision receipt, with your service's reason and reference.

Enrolling

Enrollment is a one-time ceremony by the organization's owner. It relies on that person being trustworthy at the moment they do it: Symbol cannot prove that afterwards.

Your service proves who it is in one of two ways, chosen when you enroll:

  • Secret hashes. Your service sends its secret with each request, and Symbol keeps only a SHA-256 hash of it. The secret travels to Symbol over HTTPS every time it is used.
  • Signed keys. Your service signs each request with an Ed25519 private key, and Symbol keeps only the public key. The private key never leaves your machine, so Symbol never receives anything that could act as your service. Sentinel Self-hosted uses this. The signing format is in the preview API reference, for any service you write yourself.

Both work the same way once enrolled. The choice applies to the management and recovery credentials, and each child credential your service issues later can use either.

With secret hashes

  1. On a machine your Symbol accounts cannot reach, generate two separate 256-bit secrets: a management secret and a recovery secret. Keep them there. Each must be 43 to 128 characters of letters, digits, _ or -. These commands always produce valid ones: MANAGEMENT_SECRET=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=') and RECOVERY_SECRET=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '='). The possession commands Symbol shows you read these two names.
  2. Hash each one with SHA-256: printf %s "$MANAGEMENT_SECRET" | shasum -a 256, then the same for $RECOVERY_SECRET.
  3. In your organization's Settings, open Governance, find Approval service, and register the two hashes. Symbol asks you to confirm it's you. Symbol never receives the secrets, and the page refuses and clears anything that looks like one.
  4. Symbol shows a one-time challenge and a command for each credential. Run each command where its secret is kept. The challenges are shown only once and expire within 60 minutes. If yours are gone, choose Start over.
  5. When both credentials have proved possession, choose Turn on the approval service, and confirm it's you again.

With signed keys

  1. On a machine your Symbol accounts cannot reach, generate two separate Ed25519 key pairs: a management key and a recovery key. With Sentinel Self-hosted, sentinel-selfhosted keygen writes each private key to a file only its owner can read and prints the public key.
  2. In your organization's Settings, open Governance, find Approval service, choose Signed keys, and paste the two public keys. Each is the 43 characters the key generator printed. Paste only a public key: a secret made for the Secret hashes option has the same shape but is not one. Symbol asks you to confirm it's you. The page refuses and clears anything that looks like a private key or a key file's contents, and the two keys must be different. The Signed keys option appears only when the deployment you use has the public origin it checks signatures against configured.
  3. Symbol shows the enrollment id, the origin your service must sign for and, for each key, its credential id, a one-time challenge and the sentinel-selfhosted enroll possession command that proves you hold it. Run each command where its private key is kept. The challenges are not secret: without the private key they prove nothing. They are shown only once and expire within 60 minutes. If yours are gone, choose Start over.
  4. When both keys have proved possession, choose Turn on the approval service, and confirm it's you again.

A public key registered in your organization once, in any role, can never be registered again, even after it is retired or you start over. Generate fresh keys every time you start.

An organization enrolls once. Deleting policy settings, restoring a snapshot, transferring ownership or removing members never returns it to an unenrolled state. While the service governs the organization, its owner cannot delete the organization: the management credential has to disable external mode first. The same applies to deleting the owner's account, even when the owner is the organization's only member. External mode cannot be disabled while any member is suspended: only a credential can restore a member, so restore them first.

External approvals are unavailable until the deployment you use supports them. Until then, the setting says so and owners and Admins keep deciding.

Credentials and scopes

The approval service is its own identity. It is not a person, an organization API key or a connected app, and its credentials work only on the Approvals API. A credential enrolled with signed keys accepts only signed requests, and one enrolled with a secret accepts only that secret: neither falls back to the other.

CredentialWhat it can do
ManagementIssue and revoke child credentials, change which Types are protected, suspend and restore members, replace itself, disable external approvals
RecoveryReplace itself or the management credential. It cannot read proposed content or approve anything
Child: reviewDiscover pending changes and read each revision and its difference
Child: decideApprove or reject an exact revision
Child: suspendSuspend and restore members
Child: auditRead the record of what happened

A child credential can be limited to specific Types. A decision that touches several Types needs authority over all of them, and a credential limited to Types cannot approve a Type's deletion. Children cannot widen their own scope or create other credentials.

Every decision names the exact revision and digest it reviewed and the authority version it read. If anything moved since then, the decision is refused and nothing is released.

Some work saved offline arrives as a group of new items that link to each other, so they can only be added together. Your service sees how many items the group adds and which Types they are in, and approves or rejects the whole group at once. Approving it also needs your service to confirm that it reviewed every item in the group. The group is released as the person who wrote it, through the same key or connection they used, so it is refused if that key or connection has since been revoked, has expired or lost the access it needs, or if they have been suspended.

Reviewing what is private or encrypted

Approval authority is not permission to read everything:

  • A member's Private item is left out of review entirely, including its title and its place in counts, unless that member grants your service review of it. The grant does not release anything or change who can read the item. Revoking it before a decision stops that decision. The same holds for something a change would create Private, such as the log of a Private capsule: the grant names that capsule, or the Private Type the new item would be in. A grant on a Private capsule also covers later changes to the log it owns.
  • A move of items from someone's personal workspace into your organization cannot be reviewed by your service yet: personal items cannot be granted, so the move stays out of review and its author can withdraw it.
  • For end-to-end encrypted content, your service receives ciphertext only: the approved and proposed envelopes and the manifest of what changes. Symbol does not decrypt it and holds no key to do so, and a review credential never hands out keys. To see the difference, your service runs its own decrypting reviewer, using keys obtained through your existing encryption setup.
  • On the web, an encrypted change says it is ciphertext only in that browser. The Symbol app can decrypt it on the device for anyone who holds the key, for reading.

Recovery and custody

Keep the management and recovery secrets or private keys separately, and away from anything a Symbol account can reach, such as a personal password manager tied to the same email. Keep the recovery key offline once enrollment is on: it is only needed to replace a lost or compromised management credential.

  • The management credential can replace itself. The recovery credential can replace itself or a lost or compromised management credential. The management credential cannot replace recovery. While a replacement the recovery credential started is under way, the management credential cannot start or complete one of its own, or disable external approvals, so a stolen management secret cannot stop recovery. Every replacement also proves possession of the new secret or key. When it completes, the old credential and every child credential stop working at once, and pending decisions that named the old authority version are refused.
  • There is no password, email or support reset. If you lose both secrets or both private keys, Symbol cannot give you control back. Nobody can replace a credential, issue or revoke one, change protection or disable external approvals. Child credentials already issued keep working until they expire or end, so a live decide credential can still approve; once none is left, no new change can be approved. Approved content stays readable.

Availability

Your service is now part of how changes go live, and that is a deliberate tradeoff:

  • If your service is down, changes wait. Symbol never falls back to member approval.
  • Disabling external approvals is an explicit act of the management credential, and it cannot be undone: this organization cannot enroll again. Changes waiting at that moment are cancelled, never published.
  • Plan for the service being unavailable before you depend on it, including who can reach the secrets in an emergency.

Security policies and approvals

An organization whose security policies are on can use an approval service too, whether they were on before it enrolled or turned on afterwards. The owner enrolls under the same policies as any other request they make, so a network rule, a second factor or an identity provider sign-in applies to the enrollment itself.

Your service decides whether a change is good enough to go live. It does not decide whether the person who proposed it may still write it. When your service approves a change, Symbol checks that person against your organization's security policies as they are at that moment, using what it recorded when they proposed the change. The person is not present when your service decides, so nothing about them is updated: their sign-in, idle time and grace periods are left exactly as they were.

PolicyWhat is checked when your service approves
NetworkYour allowed ranges are applied to your service's decision request. Where the author is now is not known, so it is not checked. A restricted network refuses a decision request whose address cannot be told.
Author and directoryThe author must still be a member, not suspended and not signed out of the organization since proposing. If you use an identity provider, it must still list them as active and assigned. Leaving and rejoining does not revive an earlier proposal, and an identity provider that gives no definite answer refuses the release.
Sign-in and timeThe sign-in the author proposed with must still meet your second factor, identity provider sign-in, session length and idle rules at the moment of the decision. Symbol never uses the owner's sign-in, a newer session of the author's, or your service's credential in its place.
App, key and accessThe app, key, CLI or assistant the author proposed through must still be allowed, unexpired and not revoked, and the author must still have the access the change needs. An approved service identity keeps exactly the exceptions your policy grants it.

If the author no longer qualifies, nothing is released and the change stays pending. Your service is told which rule failed, so it can wait, try again, or ask the author to withdraw the change and submit it again. Rejecting a change is never refused this way, because a rejection releases nothing. A change proposed before Symbol recorded how changes were proposed may have no record to check: approving it is refused, and its author can withdraw it and submit it again.

Approvals decided by members are unaffected: they go through the deciding member's own request, as before.

What the review page shows

The change's page, on the web and in the app, has a Security policies at release section:

  • While the change waits, it lists which groups of rules an approval will check under your current policy, so everyone can see what a release depends on. The policy can still change before your service decides. While your organization's policies are off, the section is not shown, because no security policy applies to the release.
  • Once your service approves it, it lists each group of rules as Checked, Exempt or Does not apply, with the policy version it was judged under. This is the record kept with the decision, so it stays the same when your policies change later. Your service receives the same record in its decision receipt.
  • A change approved while your organization's policies were off says so: no security policy applied, though Symbol still checked that its author was a member, was not suspended, and that the key they used, if any, was still live.
  • A change approved before Symbol kept this record says the policies were not recorded, rather than guessing.
  • A rejected change says nothing was checked for its author.

Suspending a member

The management credential, or a child credential with suspend authority and no Type limit, can suspend anyone in the organization, including its owner, without removing them. A suspended person cannot read, write, export, sync or review anything in that organization, from any device or key attributed to them. Their other workspaces are unaffected. Removing and re-inviting them does not clear it, and only your service can restore them. Restoring removes only the suspension: it does not bring back removed membership or revoked keys.

A share link works for anyone who holds it, so Symbol cannot tell who is using it. For that reason, links a suspended person issued for the organization stop working until they are restored. Symbol cannot identify a suspended person who uses a link someone else issued.

Offline and older clients

Protection governs what Symbol serves, and has limits on copies already delivered:

  • A device that is offline, or an older app or Bridge that is still running, keeps what it already downloaded. Symbol cannot erase bytes on a disconnected device.
  • Once a device connects and learns it has lost access, it removes that organization's local copy and refuses to read it. Sync pages from before the change are rejected.
  • After a restoration, the device builds a fresh copy rather than reusing anything from before.
  • Pending changes never enter local copies, so offline reading only ever shows approved content.

The record of decisions and security actions is attributable and append-only in the application. It is not a claim of tamper-proof storage against someone operating the database.

On this page