Organizations & access

Sign in to your organization

Open Organization from the workspace navigation. Enter the independently provided Organization API origin, then choose Sign in with testnet wallet. Use a wallet that supports NEP-413 message signing. The message binds your account, service, frontend origin and a five-minute nonce.

The organization service verifies the signature and the current finalized FullAccess key. A one-hour session stays in memory. Changing the API origin, leaving the page or returning from browser history clears the local session. Explicit Sign out revokes the server session.

Authentication uses an Ed25519 wallet returning the signed message directly; redirect-return callbacks are not implemented. A function-call key cannot sign in. The server checks a recent finalized testnet key on each private request and denies access when the identity RPC is unavailable.

The key response must match the requested finalized block hash and height. TLS certificate verification must remain enabled. A 25-second client deadline bounds stalled requests; caller cancellation also aborts in-flight requests.

Create and invite

1. Create an organization with a workspace name. This does not verify a legal entity.
2. Open Invitations, enter a NEAR testnet account and choose a permitted role.
3. The recipient signs in to the same organization service and accepts from Your invitations. Invitations expire after seven days; no email or Telegram message is sent.
4. Review Members to change a permitted role or remove a member. The server rechecks membership on each request. An invitation also binds its inviter’s membership version. Membership changes automatically revoke affected pending invitations; the recipient inbox hides invalid older grants. Re-adding an inviter cannot revive old authority.

Corporate payment approval

Approved terms are read-only. Changing the recipient, token, amount, policy, proof/reference or storage/registration call requires cancellation before any reservation and a new independent approval. Viewer cannot read corporate requests; Auditor can read but cannot approve or execute.

The API binds approvals to both membership revisions and a fixed 24-hour expiry. Role changes, removal/rejoin and ownership transfer invalidate old approval. Each reviewed call is durably reserved once; lost HTTP/wallet responses stay blocked for reconciliation. No automatic retry or reservation-reset action exists.

This policy is enforced by the Organization API, SDK and supported wallet flow. The underlying contracts retain permissionless fixed-destination proof execution; anyone holding a valid public withdrawal plan can relay it outside this workspace. Wallet-account separation is not verified separation of real people or corporate identity. Contract-enforced dual approval remains separate work.

1. Select Payments. Import the independently trusted testnet FT policy and matching Settlement API origin.
2. As an Owner, Admin or Operator, open Prepare a new payment. Import the public withdrawal plan generated locally from the original note, set its title and request independent approval. The creator must be its fee payer.
3. A different Owner/Admin opens the request, independently trusts the same policy and reviews recipient, full principal, additive 0.15% fee, reference, expiry and exact prerequisite calls. Choose Approve exact payment; self-approval is refused.
4. The creator refreshes Payments and unlocks the encrypted corporate operation journal. Review and sign each exact prerequisite/payment. Current memberships, independent approval and complete call content are checked immediately before provider dispatch.
5. Confirm the bound finalized withdrawal through the journal. A dispatch reservation is not payment confirmation; preserve encrypted backups and reconcile uncertain results instead of resending.

Roles and permissions

Roles are fixed. The server checks organization membership on every request. UI controls are not an authorization boundary. Corporate payment permissions now separate preparation, independent approval and execution of the creator’s exact payment in this workspace. They do not grant wallet keys, invoice ownership or contract-enforced treasury authority.

Membership limits and audit history

Creation, renaming, invitations, member changes and ownership transfers append to the audit log in the same database transaction. Failed or stale changes do not append a successful change. This application history can be altered by a database administrator; it is not an independently anchored payment or tax proof.

Ownership and recovery

An organization always has one active Owner. An Owner must explicitly transfer ownership to an active member before leaving. The former Owner becomes an Admin. Version checks reject stale changes; refresh before retrying.

An accepted member can leave. Removing a member immediately blocks their organization access. Membership changes revoke affected pending invitations and record the revocation atomically. Older invalid invitations are filtered out of recipient inboxes. There is no platform-admin owner reset, lost-wallet recovery or corporate multisig workflow.

Resolve access and version errors

The browser clears credentials and private views on page-hide, history-cache return, unmount or API-origin change. Explicit Sign out revokes the server token. If logout transport fails, local credentials are still cleared; server revocation remains unconfirmed until expiry. A submitted request may already have committed.

A failed request clears cached organization, member, invitation, audit and role views. A failed initial access load also clears the new local session. Refresh and reselect the organization before another write. Proxy responses with invalid JSON preserve their HTTP denial status.

Data and service boundary

Organization data is kept off-chain in a separate authenticated SQLite service. Names, wallet membership and audit metadata are not application-encrypted; the host must protect its volume and backups. No private note, payment key, identity document or salary is submitted to this API.

The Sites preview remains owner-private. Self-hosted access follows the host configuration; organization membership and hosting access are separate boundaries. Accepted HTTPS backend hosting and a funded testnet wallet journey remain deployment tasks.

Account-based maker-checker approval is now available in Payments. Business verification, verified corporate signer mapping, contract-enforced approval, custom roles, SSO and automatic signing remain separate work. The public read-only settlement API continues to require independently trusted deployment policies.

Server backup and access recovery

Operators use the dedicated organization CLI, independently of the public settlement index. Online SQLite backup includes committed WAL data while leaving the live service unchanged. Exported and restored files are quarantined, contain no sessions/challenges and cannot start a service.

Generate an access-review template for the exact restored file. It intentionally includes no historical owner or member grants. Approve current account roles and revisions using independent current authority; obtain the approved file hash separately. Missing authority leaves the service quarantined.

Activation writes a new database, revokes all historical members and pending invitations, grants only explicitly reviewed access, advances versions and appends recovery audit. A durable one-use intent blocks competing/replayed activation of that recovery file. A crash with an uncertain activation needs inspection and, if necessary, a new restore/review.

Corporate payment requests and call reservations are included in server snapshots. Pending, approved and dispatched requests become invalidated during backup/restore; membership reapproval does not reapprove payments. Existing reservations remain consumed for conservative reconciliation.

These are protected operator commands, not browser membership actions or a self-service lost-wallet reset. Stop old instances before cutover, use the same API audience and sign in again. Keep database, review and activation-intent files private; encryption, off-host retention and current-authority approval remain operational responsibilities.

npm run build:service
# CORE_ORGANIZATION_DB points to the live database.
npm run organizations:backup -- /private-backups/new.sqlite
# Select a NEW quarantine path in CORE_ORGANIZATION_DB.
npm run organizations:restore -- /private-backups/new.sqlite TRUSTED_BACKUP_SHA256
npm run organizations:review-template -- /private-reviews/access.json
# Independently review current authority, then select a NEW active database path.
npm run organizations:activate -- /private-recovery/quarantined.sqlite /private-reviews/access.json APPROVED_REVIEW_SHA256

Organization invoice API

The separate Organization API accepts immutable merchant-signed invoices at POST /v1/organizations/:org/invoices. Use a stable requestId for retries. Exact repeats return the existing record; changed terms under an existing request or merchant invoice ID return a conflict. GET the collection with its before cursor or retrieve a record by storage ID.

Owners, Admins and Operators can save and read; Auditors can read; Viewers cannot access invoices. New invoices require the authenticated merchant’s current FullAccess key and a valid NEP-413 signature. Invoice storage does not grant wallet authority or mark a payment complete.

Operators must provision CORE_ORGANIZATION_INVOICE_KEYS_FILE separately from the database and backups. Signed terms use AES-256-GCM encryption, with keyed tenant-bound indexes for duplicate detection. Without keys, invoice storage is disabled. Organization IDs, timestamps/counts and existing membership/audit metadata remain visible to the database operator. Authorized readers and the live service can access plaintext.

Keep every data key needed by retained backups and the stable index key. Reviewed organization recovery restores ciphertext and retry indexes, drops sessions and requires current access approval before activation. The current browser invoice form/library remains independent; the organization payment dashboard now provides search/filter/export; signed payment webhooks are now available through the optional Organization delivery worker.

npm run organizations:invoice-keys -- /absolute/private/service.invoice-keys.json initial
export CORE_ORGANIZATION_INVOICE_KEYS_FILE=/absolute/private/service.invoice-keys.json
npm run serve:organizations

Manage invoice payments

Open Organization, sign in, choose your team and select Invoice payments. Owners, Admins and Operators can explicitly save merchant-signed JSON; Auditors can read/check/export; Viewers cannot load invoices. The full authorized snapshot is signature-verified and loaded in bounded pages before display.

Search titles, references, IDs, merchants and recipients. Filter payment status, asset, group and inclusive UTC issue dates. The table shows 20 rows per page. CSV/JSON exports include all filtered rows across pages, exact atomic amounts, linked finalized record/transaction identifiers and checkpoint metadata. Exports contain readable business details; protect downloaded files.

Under Settlement source, independently import the trusted policy and enter its matching Settlement API. Check payments reads every loaded invoice matching that exact policy, at most one per second. Large collections take longer and can be cancelled. Source changes discard previous observations; other groups stay unchecked. Current private read access is checked before publishing each result or exporting.

Only matching finalized successful withdrawals count. Wallet callbacks and redirects never mark paid. Unknown/error observations stay Unchecked or Unavailable; index/browser observations older than five minutes become Stale index. Incomplete coverage and reused v2 unit references need review. Every result retains its observed height/time and chainFreshnessChecked: false.

Historical signed invoice records can be reconciled after a merchant key rotation; checkout still requires a current merchant signing key. Organization switching, page-hide and revoked access clear cached private data and reject late responses. No plaintext browser invoice/status cache is created.

Manage signed payment webhooks

Open Organization → Webhooks. Owners and Admins can create approved HTTPS callbacks, pause/resume, rotate a signing secret and retry failed or recovery-held deliveries. Operators and Auditors can read callback/delivery history; Viewers cannot load it. Prepare and securely save a random 32-byte base64url signing secret in your receiver first; the API never returns it.

Operators enable the worker with a separately protected organization key ring, a local verified finalized SQLite index, its exact reviewed testnet policy and independent SHA-256, and exact approved HTTPS callback origins. Callback URLs cannot contain credentials, queries, fragments, IP literals or alternate ports. Every send checks public DNS addresses, pins the socket, verifies hostname TLS and refuses redirects.

Each matching finalized successful withdrawal with linked transaction provenance creates one immutable invoice.payment_confirmed event. Incomplete/stale coverage, failed attempts and unlinked records do not issue confirmations. Events and per-endpoint delivery uniqueness are committed atomically. Historical payments can catch up; new endpoints can receive an existing event without resending successful old deliveries.

Every attempt carries an HMAC-SHA-256 signature over the exact raw body, stable event ID, key ID and fresh Unix timestamp. The receiver must enforce the five-minute timestamp window and atomically deduplicate event IDs. A sender can retry after a lost acknowledgement even when the receiver already committed; acknowledge 2xx only after idempotent business work commits.

Network/transient HTTP failures retry with bounded backoff up to eight attempts per cycle. Redirects and permanent errors become dead letters. Inspect attempt outcomes, safe error/status codes and next due time; a current Owner/Admin can explicitly redrive a dead/held delivery up to three cycles with the same event ID. Delivered jobs cannot be manually resent.

Encrypted backups retain events and attempt/dedup history but pause restored callbacks and hold pending/in-flight sends. Current access review, explicit resume and held-job retry are required. Webhook metadata and protected database state remain visible to the service; signing secrets, callback paths and event bodies are encrypted at rest.

AI tax and procedure drafts

Owner/Admin/Operator can create; Auditor can read/export; Viewer cannot read drafts. Failed or uncertain model requests are not replayed automatically: inspect the pending generation after reload and explicitly abandon it if needed. Abandonment blocks late persistence but does not guarantee provider cancellation.

The operator must configure protected encryption keys and optionally a private AI key/model. Accepted review requires an independently pinned reviewer policy; bundled rule candidates have no professional approval. Evidence integrity against your supplied root does not establish factual truth, independent anchoring or payment finality.

1. Open Tax drafts. Import a Rules report and a selected evidence receipt, enter its independently obtained root, label it, and bind the disclosed amount to the exact report fact. The declared fiat currency must match; no token/FX inference occurs.
2. Save a deterministic outline or, when configured by your operator, generate an AI-arranged draft. The model sees categorical IDs only. Exact calculations, source URLs/digests, receipt bindings, uncovered facts and limitations are rendered locally by the service.
3. Submit the immutable revision for a different Owner/Admin to review. Request changes creates a new revision; approvals require explicit basis/evidence/scope acknowledgements, current signed rules and unchanged author/reviewer memberships.
4. Export authorized current JSON or cited Markdown. Internal approval expires within 24 hours and can be withdrawn. Restore invalidates approvals. No filing or payment is authorized.

Pay workers and contractors

Open Organization → Payouts. A run groups 1–20 public corporate withdrawal plans under one exact trusted testnet FT policy and fee payer. Every row spends a distinct funded note, derives its principal and added 0.15% fee from policy and needs another Owner/Admin’s independent approval. Worker/contractor categories are declarations, not employment or tax verification.

Import the independently trusted policy/Settlement API and a saved core-payout-manifest-v1 file containing stable batch/row IDs and public calls. The SDK stages rows idempotently before committing immutable ordered batch links. Retry the same file after a partial/lost response. Private notes, witnesses and wallet keys are not accepted.

Review each recipient’s full principal, added token fee, permitted prerequisite calls and maximum attachments. Include independently reviewed initial/later storage prepayment variants when needed; preflight cannot silently raise an approved charge. The creator cannot self-approve. Existing row expiry and maker/approver membership revisions remain active.

The creator unlocks one encrypted original-group journal, reviews the selected recipient and explicitly signs each next exact call. Other approved rows remain independent. An accepted failed withdrawal can retry only its original recipient/nullifier with additional NEAR storage, without a second withdrawal token fee. No action silently resends an entire run.

Reconcile recipient payouts reads and binds every final contract state separately. Unobserved/unknown results are not failed-payment instructions. Completed journal rows stay closed even if later reads regress; reports preserve last confirmed observations while flagging stale/unavailable/inconsistent results. CSV/JSON export separates quotes, historically confirmed principal and principal not yet confirmed.

Keep encrypted journal/note backups. Lost authorization or wallet responses require original-transaction reconciliation, never resetting consumed dispatch reservations. Restored organization data preserves batch links but invalidates old approvals and keeps note claims. These controls are an application workflow; the contracts retain permissionless fixed-destination proof execution.