View as Markdown

Identity & access — concepts

Identity in Vectros answers two questions on every request: who is acting, and what are they allowed to touch. The model spans the whole range from the company that builds on the platform down to a single end-user inside one of that company's apps — and it turns "who is this" into "what operations, on what data" through one small set of primitives. Every API call carries a credential; every credential resolves, at the edge, into a principal, a tenant, an app context, and a scope before the request reaches any application code.

Vectros began as the back-end for a HIPAA-grade clinical product — battle-tested in production against regulated health data before it was offered as an API. The data-isolation, audit, and scope-enforcement primitives described here were designed for that bar, and they apply unchanged to every workload built on the platform.

This page is the mental model. For runnable steps, see how-to.md; for the exhaustive surface — every method, field, limit, and error — see reference.md.

The isolation moat: app contexts

Start here, because everything else rests on it. An app context is a hard partition. Every piece of data you store — records, documents, folders, and the schemas that shape them — lives inside exactly one context, identified by a contextId. The context is not a label you attach and could forget: it is a mandatory, fail-closed partition key that is derived from the calling credential, never accepted from request input. A caller cannot ask to read another context's data, because there is no request shape that lets them name a context they aren't authenticated into. Lookups are same-context-only by construction.

This is the multi-tenant isolation boundary. If you are building a platform that serves your own customers — a SaaS product, a per-clinic clinical tool, a per-team knowledge base — you give each customer their own context and their data can never bleed across. The guarantee is structural, not a per-handler runtime check that a later change could quietly regress.

A contextId is a stable, human-meaningful string matching ^[a-z][a-z0-9-]{2,30}$ — for example customer-portal, clinic-intake, or internal-admin. You create contexts through the context lifecycle endpoints (create / get / update / list / delete). On the API, creating and deleting a context is a root-key (sk_*) operation — a scoped key or token cannot provision or tear down a context, even with the wildcard * scope. Account owners can also create and delete contexts from the dashboard or the CLI: those paths hold the authority server-side behind the owner's sign-in, so no provisioning- or teardown-capable credential ever reaches a browser or a keychain. Certain context ids are reserved by the platform and cannot be created by a tenant — for example vectros-admin, which backs the hosted admin surfaces, and default, the base context auto-provisioned for every tenant.

A single company can run many contexts. A business that operates both a customer-facing portal and an internal admin tool can model them as two contexts and grant the same person different permissions in each, without one app's roles polluting the other's.

Deleting a context is deliberate and irreversible: it is a confirm-gated, asynchronous cascade. The delete call must carry a confirm token equal to the contextId, or it is rejected before anything is touched. With the token, the context flips to a purging state immediately and drains all of its records, documents, folders, schemas, roles, and profiles in the background, reaching deleted when the drain completes. This per-context hard-delete is implemented and live. (It is a different mechanism from end-subject data deletion — do not conflate the two.)

The identity plane: users and identity entities

Alongside the data, Vectros models the people and groups a request can be attributed to and scoped against. These live on the identity plane, addressed through client.identity.*, and are tenant-wide — they exist independently of any one context and are referenced by data and by credentials rather than owned by a context.

There are two identity dimensions:

  • Users represent individual people or machines acting in your tenant. A user is either a HUMAN identity — a real person who authenticates through a login system (your own auth, or a hosted one) — or a SERVICE identity — a machine principal that does not log in interactively and instead acts under a credential. The two share one model and one code path; only the type differs.
  • Identity entities are the groupings you define — a clinic, a department, a team, a customer relationship. Rather than a fixed pair of types, Vectros models every such grouping as one generic entity type, addressed by namespace: org and client are two reserved, built-in namespaces that exist for every tenant automatically, and anything else — team, project, department — is a namespace you register yourself before it can hold entities. Records, documents, and users can be tagged with one or more entity references — up to two, each in a different namespace — through the scopes field. The reason identity entities are first-class platform objects — rather than free-form metadata — is that they participate directly in scope enforcement: a credential can be narrowed to a specific entity, and the narrowing is checked against the row's own ownership fields on every read, write, and search, not against a per-document access list.

Namespaces: anchoring your own ownership axes

A namespace is a name you can reference in a scopes entry (<namespace>:<value>). org and client ship pre-registered; anything else you use — region:us, team:eng — is a free-form string by default, validated only for grammar. To turn a namespace into a real, enumerable entity type — one you can create, list, look up by schema field, and that the platform existence-checks on every reference — you register it: POST /v1/namespaces with { namespace: "team", entityBacked: true, specificityRank: 10 }. Once a namespace is entityBacked, every scope:team value anywhere on the platform (record ownership, dataScope, identityOverrides) must resolve to a real entity created via /v1/entities/team, or the write is rejected — the same anchoring org and client have always had, now available for any axis you define. Registering or changing a namespace is a root-key-only operation; reading the registry (GET /v1/namespaces, which always lists the two built-ins alongside anything you've registered) is open to any credential. A namespace cannot be deleted, or flipped back to free-form, while entities still exist in it.

specificityRank is a required, account-unique integer position in your account's specificity order (registering or updating a namespace without one is rejected with a 400). It exists to break ties: when a basedOn schema lookup finds a caller holding two scope dimensions at once (e.g. both org and team), the higher-ranked namespace's variant wins. Pick an order once and leave headroom between values (10, 20, 30, …) so a later namespace can slot in between without renumbering everything else.

An identity entity's own ownership is expressed the same way records' is: its scopes field carries up to two parent edges, each <namespace>:<value>, and each in a namespace different from the entity's own (a team entity's parents can be org:... and one more, but never another team:... — a value in an entity's own namespace names a peer, not a parent). Read back, an entity's scopes are its effective scopes: its own reference (<namespace>:<its id>) followed by its parent edges — so you can quote a GET's scopes value directly as an ownership reference elsewhere.

External IDs make identities idempotent

You arrive with users, customers, and accounts that already have IDs in your own systems — emails, UUIDs, your billing provider's customer IDs, your auth provider's subject IDs. Every identity carries an externalId that you supply, so you don't have to maintain a separate mapping table. Create is idempotent by externalId (per user, and per (namespace, externalId) for an entity): a second create with the same externalId returns the existing identity (it does not duplicate, and it does not overwrite — the second call's other fields are ignored on the idempotent return, unless you pass ?upsert=true on an entity create, which overwrites instead). The encoding that carries an external ID into storage is permissive about characters — the variety of legitimate formats is too wide to allow-list — so values containing separators like : or # round-trip cleanly, and you never see the encoded form.

Each identity dimension supports the full lifecycle: create, get, update (a full-replace PUT), delete, list (filterable by externalId, and entities additionally by ?scope=<namespace>:<value> — one parent per query — and by schema field), and a version history read. There is no partial-update (PATCH) on the identity plane today — updates replace the identity body.

The access model: scopes, profiles, and roles

A credential is only as powerful as its scope. Scope has two halves: which operations it permits, and which data it may touch.

Scope grammar

An allowed action is a string of the form resource:ops[:qualifier]. The operations are the single letters c (create), r (read), u (update), d (delete), freely combinable — records:r is read-only on records, records:cru is create/read/update, records:r:intake_form narrows read to one record type. The data-plane resources are records, schemas, search, documents, folders, and inference. Identity entities are a control-plane resource, granted as entities:ops:<namespace> (mirroring the records:ops:<type> qualifier form) — a human grants this deliberately through the developer portal; it is not something an automated bootstrap can mint (below). Your tenant's own users are a separate control-plane resource, granted as plain users:ops for the four CRUD letters — a qualifier there is rejected, since users aren't typed the way records or entities are. The fifth op letter, s, is the exception: if a user carries a governing schema (schemaId), users:s:<schemaType> reveals that type's sensitive fields, the same qualifier form as documents:s:<type>. The developer portal's scope editor also offers users:crud as a one-click shorthand for the four CRUD operations.

Two grammar facts matter enough to lead with, because getting them wrong fails silently:

  • Author explicit resource:op forms. A coarse verb (a bare read or write) and the operations-wildcard form resource:* grant nothing at runtime. Always write the letter form: records:r, search:r, documents:cru.
  • The single literal * is the only true wildcard — it grants everything, and it is the shape carried by root keys (below). Reserve it for that.

Data scope

The second half is dataScope — a map from an ownership dimension to the list of values the credential may touch. userId is its own fixed dimension; every other dimension is a namespace, keyed as scope:<namespace>:

{ "dataScope": { "scope:client": ["client_abc"] } }

A credential scoped to { "scope:client": ["client_abc"] } cannot touch rows whose client scope entry is anything else. The same filter applies to list and search as a server-side narrowing that sits below any caller-supplied filter and can never be widened by it. Multiple values in one dimension's list match the union; multiple dimensions intersect.

dataScope is strict by default: a scoped credential must include the matching filter on each list and search call (?userId= for the userId dimension, ?scope=<namespace>:<value> for a namespace dimension — one scope filter per query), or the request is rejected with a message naming the required dimension. Strict-scope forces the caller's intent to be explicit at the request boundary. To also reach tenant-level data — rows with no value for the scoped dimension, i.e. shared data not assigned to any owner in that dimension — the caller adds a JSON null to the value list: { "scope:client": ["client_abc", null] }. The null is an explicit, opt-in widening to owner-less data; it is never implicit.

The same values also gate what a credential may place on a write, not just read. A credential that carries a dataScope for a dimension but no fixed identity of its own must state ownership when it creates an item: a create that omits scopes for that dimension is refused rather than silently producing an account-wide (owner-less) item. To create an account-wide item on purpose, include a JSON null in that dimension's dataScope value list (the same explicit opt-in that widens reads also authorizes an owner-less write). Ownership is never assigned implicitly.

A dimension a credential's dataScope says nothing about is not narrowed on reads — but it also cannot be written into. If a credential needs to place data in a given dimension, that dimension must be named in dataScope (explicitly, or via the "*" default-dimension form described under roles below); a clause that never mentions a dimension grants no way to stamp a value into it on create or update.

Access profiles and roles

An access profile is the per-principal, per-context permission row that the scope model is built from. It binds a principal (a usr_<userId> or a key_<keyId>) to a permission shape inside one context. A profile carries exactly one of: a set of inline scopes, or a reference to a reusable role by roleId — the two are mutually exclusive (switching from one to the other clears the unused half). Profiles can be active or suspended, and suspending one denies access without deleting it.

A role is a context-scoped, identity-agnostic permission shape — define engineering-member or support-readonly once, then bind many principals to it through their profiles. This is the reusable-permission primitive: roles are multi-clause (each clause is an (allowed_actions, dataScope) pair, and any clause that matches grants access), which lets one role express a compound shape like "full control over the records I own, plus read access to the rest of the team's." A role's data_scope clauses accept a small placeholder grammar, not just literal values:

  • ${{ self.userId }} and ${{ self.scope.<namespace> }} (e.g. ${{ self.scope.org }}) resolve to the acting principal's own value at runtime.
  • ${{ any }} claims a whole ownership dimension without enumerating its values — it matches any value present in that dimension (pair it with a null entry to also cover owner-less rows).
  • ${{ under.self.userId }} and ${{ under.self.scope.<namespace> }} match values whose immediate parent is the credential's own — one level only, not a full ancestor walk — so a credential confined to an org can work with the clients under it without naming each one at mint time.
  • A dimension key of "*" states a default rule for every dimension the clause doesn't name explicitly; a dimension named directly always takes precedence.

A null data-scope sentinel additively grants tenant-level (owner-less) records. Any other ${{ ... }} spelling is rejected at authoring time with a 400, never silently stored as an inert literal.

A profile can be cleared safely: deleting a role that a profile still references is blocked (the platform refuses to orphan a profile's binding). And a profile's identityOverrides — the ownership values stamped onto what the principal touches — accept any scope:<namespace> key (reserved or one you registered, up to two total); the tenant identifier and userId are sacred and rejected, so a profile can never forge a different user's identity. The override value is authorized like scopes — even when the request body carries only identityOverrides: a scoped credential may override only to a value it itself holds (a 403 otherwise), and a root key's override must reference an entity that exists (a 400 naming the value otherwise). The check runs on the value being replaced, not only the value being set: changing or clearing an identityOverrides entry — including wiping it via an empty map — is refused with a 403 unless the caller also holds the value it would overwrite, and deleting a profile outright is refused the same way when its identityOverrides holds a value the caller doesn't hold. This is unaffected when you give your own identity to a profile that previously had none, when you edit or delete a profile whose identity is already yours, or when you omit identityOverrides entirely — and root API keys are exempt from this check throughout.

Profiles are addressable across contexts: a single lookup can answer "every context this principal has access to" — useful for an admin view of one person's reach across all the apps you've provisioned.

Note on minting profiles via the API. The profile-create endpoint accepts one scope clause per request today. Multi-clause shapes are expressed through roles (which a profile then references) or through blueprints. See reference.md for the precise limit.

Inviting a sub-user by email

A user doesn't have to be created directly — you can invite one into a specific app context instead, and let them complete their own onboarding. Inviting creates a PENDING user and binds an access profile to it in the same call: the invite carries exactly one of roleId or inline scopes, the same mutually-exclusive choice a standalone profile makes. Vectros emails the invitee an accept link, or — with sendEmail: false — hands you the raw token and a ready-made link so you can deliver it through your own provider instead. The invitee finishes the flow themselves, typically after authenticating with your own login system: an update to their user record carrying the invite token, their externalSubject in your auth system, and an attestation that you verified their email flips them from PENDING to ACTIVE.

Inviting is idempotent on the pair (context, email) — inviting the same address into the same context again rotates the token and resends the invitation rather than creating a duplicate, and a dedicated resend call does the same without touching the bound permissions. A 409 means the email already belongs to an active or suspended member of that context, or already has an identity elsewhere in your account — an email can belong to only one tenant per account, so a live and a test environment can never share one.

Five behaviors worth knowing:

  • You cannot invite someone into more than you yourself hold. Whether the invite's accessProfile is an inline scopes list or a roleId, the resolved scope is checked against your own credential's scope before the invite is created — inviting into a role or scope set broader than what you hold is rejected rather than minting a member who out-scopes their inviter.
  • Invitations always land in your live tenant, regardless of which environment your credential authenticates against — there's no such thing as a test-tenant invitation.
  • email is frozen while an invitation is outstanding. You cannot redirect a pending invite to a different address by editing the user directly — delete the pending user and re-invite instead. The address is editable again once the invitation is accepted or the user is removed.
  • An invite's roleId must name a role that already exists in the context, exactly like a standalone access profile — inviting someone into a role you haven't created, or mistyped, is rejected outright rather than creating a member who could never authenticate.
  • Resending needs more than creating. Creating a new invitation takes the create action on users; resending it — through the dedicated resend call, or by re-inviting the same address — additionally requires the read and update actions on users. Without both, the attempt is refused rather than silently rotating someone else's pending invitation.

Credentials: root keys, scoped keys, and short-lived tokens

Three credential types cover three lifecycles. All three are presented the same way on the wire — an Authorization: Bearer … header — and all three resolve through the same edge authorizer, which classifies the credential by prefix, validates it, and injects the resolved tenant, principal, context, and scope into the request before any application code runs.

  • sk_live_* / sk_test_* — root keys. One live and one test key, each with wildcard scope and full authority within its tenant. Intended for server-to-server calls from your own backend. The raw secret is shown once at creation and never again — the platform stores only a hash. The two prefixes track the two environments (a live tenant for production, a test tenant for development), with fully isolated data and indexes between them.
  • ssk_live_* / ssk_test_* — scoped keys. Permanent, least-privilege keys that are identity-bearing on the data plane: the key is bound to a principal that already has an access profile in a context, the bound principal is the data-ownership identity, and it can never exceed that profile. Minting one also requires the caller to hold the identity the bound profile carries — a scoped credential minting on another principal's behalf is refused with a 403 if it doesn't hold that identity itself; a root key is exempt. Scoped keys are the right shape for a local agent, a per-team-member bot, or any long-running worker that has no way to refresh a token and where audit attribution ("Alice's agent did this") matters. The raw secret is shown once; there is no in-place rotation — rotate by revoking and re-issuing.
  • st_* — short-lived tokens. Minted on demand, scope embedded in the token itself, default 1-hour lifetime, 24-hour maximum. These power the front-end-safe pattern (below). They cannot be revoked in flight — expiry is the lever, so mint with a short lifetime to bound blast radius.

The front-end-safe minting pattern

Browser code cannot safely hold a root key. The front-end-safe pattern keeps your backend in the loop only for minting:

  1. Your backend holds the long-lived sk_* (or an ssk_*).
  2. On login, it mints an st_* narrowed to that one user's scope — typically dataScope: { userId: ["<that user's id>"] } plus the session's allowed actions — with a short lifetime.
  3. It hands the st_* to the browser. The browser calls Vectros directly.

The root key never crosses the network boundary, the per-session token cannot widen its own scope, and a compromised browser exposes one user for at most the token's lifetime. Every minted token also records which key minted it, so audit attribution is never ambiguous — even for tokens that carry no user (a public search page, a service-to-service call).

The blueprint scope gate

The CLI and blueprint bootstrap flow — which provisions a context, principal, profile, and a narrow ssk_* from a declarative app definition — runs behind a hard scope gate. The gate mints keys for the data plane only: records, schemas, search, documents, folders, inference. Any control-plane scope (keys, profiles, app-contexts, users, billing, admin, and entities — creating or managing identity entities, including org/client) and the literal wildcard are hard-rejected — the bootstrap mints nothing and exits non-zero, with no override flag. The trust boundary is the tool, not the app definition it reads: a control-plane scoped key is something a human creates deliberately in the developer portal, never something an automated bootstrap can be talked into minting. A blueprint's identities: block (see clients/blueprints.md) works around this the other way — it declares principals for the loader to resolve via the ordinary identity API using the bridge token's own authority, rather than minting an entities scope for the bootstrapped key itself.

Revocation and propagation

Revoking a key (sk_* or ssk_*) is not instantaneous — caches at the edge mean a revoked key keeps working until the edge authorizer cache expires, up to about five minutes. st_* tokens cannot be revoked at all; they expire on their lifetime. Plan rotations and offboarding with that propagation window in mind. See reference.md for exact figures.

Where to go next

  • how-to.md — runnable guides: create identity entities and a user, register a custom namespace, mint a least-privilege scoped key, operate inside a context, wire the front-end-safe pattern.
  • reference.md — exhaustive identity/access surface: every method, field, scope-grammar rule, limit, and error.
  • ../search-rag/explanation.md — how scope and dataScope narrow search results at the data layer.
  • ../data-model/explanation.md — how records and documents pick up ownership and live inside a context.
  • ../operations-trust/explanation.md — how isolation, least-privilege, and audit history compose into the platform's compliance posture.
  • The generated API reference (rendered from the OpenAPI specification) — the canonical, always-current request and response shapes.