Identity & access — how-to
Goal-oriented, runnable guides for modeling who acts in your tenant and scoping what they can touch. Every snippet uses synthetic data only and is grounded in calls that run against the platform. For the concepts behind these steps, read explanation.md; for every option and limit, see reference.md.
Snippets use the Node SDK unless the CLI is the more natural surface. The API spec is
currently at 0.50.0; every first-party client is on a matching pin. The generic
identity-entity surface (/v1/entities/{namespace}, /v1/namespaces) needs at least a 0.35
client.
Construct a client
Every guide assumes a constructed client. You build it once with a token and an environment (the API base URL), then call sub-clients grouped by area.
import { VectrosClient } from '@vectros-ai/sdk';
const client = new VectrosClient({
token: process.env.VECTROS_API_KEY!, // sk_live_* for production, sk_test_* for dev
environment: 'https://api.vectros.ai', // staging: https://api.staging.vectros.ai
});
Sub-clients you'll use here: client.identity.* (users, identity entities, namespaces),
client.auth.* (contexts, roles, access profiles, scoped keys, token minting), and
client.records.* / client.search.* to exercise a scoped credential.
Create identity entities and a user
Goal: model one customer organization and one person inside it, using the reserved
org namespace.
Prerequisites: a root sk_* key (or any credential permitted to manage identities).
Identities are idempotent by the externalId you supply. A user, and an entity in a tenant-wide
namespace, are tenant-wide and orthogonal to app contexts — you create them once and reference
them everywhere; an entity in a context-owned namespace belongs to that context (see
Namespaces, below). org and client are
reserved namespace names, but not exempt from registration: register both once, the same
one-time, root-key step as any other namespace (see Namespaces, below), before creating
entities in them.
// 0. Register the org and client namespaces (one-time, per account — skip if already done).
await client.identity.registerNamespace({
body: { namespace: 'org', entityBacked: true, specificityRank: 1000 },
});
await client.identity.registerNamespace({
body: { namespace: 'client', entityBacked: true, specificityRank: 2000 },
});
// 1. Create the org entity. `externalId` is YOUR id for it; create is idempotent on it
// within the `org` namespace.
const org = await client.identity.createEntity({
namespace: 'org',
body: {
externalId: 'clinic-001',
name: 'Northside Family Clinic',
payload: { region: 'northeast' }, // free-form attributes, round-tripped as-is
},
});
// org.id is the Vectros-assigned UUID — use it in a `scopes` entry ("org:<org.id>") below.
// 2. Create a HUMAN user. Users carry `email`, not `name`, and are not namespaced.
const user = await client.identity.createUser({
body: {
externalId: 'user-jdoe',
email: 'jdoe@example.com',
payload: { profile: { role: 'clinician' } },
},
});
// 3. Create a client entity (an external customer you serve), owned by the org.
const customer = await client.identity.createEntity({
namespace: 'client',
body: {
externalId: 'cust-1042',
name: 'Jane Doe',
scopes: [`org:${org.id}`], // parent edge — must be a DIFFERENT namespace than "client"
},
});
Expected result: each call returns the created identity with status: 'ACTIVE' and its
Vectros id. An entity's scopes on read is its effective scopes — its own reference
followed by its parents, e.g. ["client:<customer.id>", "org:<org.id>"]. Re-running any
create with the same externalId (within the same namespace, for entities) returns the
existing identity unchanged (the other fields on the second call are ignored) — so
these calls are safe to repeat. Pass ?upsert=true on a user or entity create if you want a
repeat call to overwrite instead. An update or upsert that meets another write to the same item at
the same moment returns 409 (VERSION_CONFLICT) with nothing written, whether or not you send
expectedVersion: re-read the item and retry. A user update is retried a few times first, so
it returns 409 only if the user keeps changing.
To create a machine identity instead of a person, pass type: 'SERVICE' to
createUser. A service user is the principal a long-running agent or scoped key acts as.
The same flow on the CLI:
vectros identity create --type org --external-id clinic-001 --name "Northside Family Clinic"
vectros identity create --type user --external-id user-jdoe --email jdoe@example.com
vectros identity create --type client --external-id cust-1042 --name "Jane Doe" --scope org:<orgId>
# Make a SERVICE user (machine principal) instead of a HUMAN one:
vectros identity create --type user --external-id agent-bot --service
--type takes user or any namespace — org and client are reserved names, and any
namespace you've registered (next section) works identically once registered. Look identities up by your own id with
vectros identity list --type org --external-id clinic-001.
Register a custom namespace and create entities in it
Goal: model an ownership axis of your own — a team — the same way org/client
work, so it can be created, listed, looked up, existence-checked, and used to scope
credentials.
Prerequisites: a root sk_* key. Changing or deleting a namespace needs a root key, as
does registering one through the API (the CLI path is noted below); reading the registry is
open to any credential.
// Register the namespace. entityBacked: true is what turns "team:<anything>" from a
// free-form label into an anchored, existence-checked entity reference. specificityRank
// is required — a unique integer position in your account's specificity order, used to
// break a tie when a caller holds two scope dimensions at once during schema resolution.
// Leave headroom between values (10, 20, 30, …) so a later namespace can slot in between.
await client.identity.registerNamespace({
body: { namespace: 'team', entityBacked: true, specificityRank: 10 },
});
// Create entities in it exactly like org/client.
const team = await client.identity.createEntity({
namespace: 'team',
body: {
externalId: 'team-eng-platform',
name: 'Platform Engineering',
scopes: [`org:${org.id}`], // a team can itself have a parent org
},
});
Expected result: GET /v1/namespaces now lists team alongside org and client (once
you've registered those too — step 0 above). From this point, a scope:team value anywhere
on the platform (record scopes, a token's dataScope, a profile's identityOverrides)
must resolve to a real team entity or the write is rejected — the same existence check
org/client get once registered. A
namespace cannot be deleted, or flipped back to entityBacked: false, while entities still
exist in it.
Registering a namespace is a deliberate act: it needs a root key, or the CLI bootstrap's provisioning capability, which can register only a context-owned namespace in the context it provisions. A tenant-wide namespace needs a root key or a further owner-only capability, and the CLI's
--allow-tenant-wide-namespacesflag when a blueprint requests one (see explanation.md). On the CLI,vectros namespace register team --context clinic-a --specificity-rank 10 --entity-backeddoes that;vectros namespace listandvectros namespace get teamread the registry. A blueprint's top-levelnamespaces:block registers its namespaces during apply, while itsidentities:block only declares entities to create in a namespace that is already registered.
The registration above is tenant-wide —
teamis shared by every app context, the default. Pass?contextId=(registerNamespace({ body: {...}, contextId: 'clinic-a' })) to make it context-owned instead: a second context can then register its own, unrelatedteamnamespace with no collision, and every/v1/entities/teamcall (including thiscreateEntity) must then also carry thatcontextId. Placement is fixed once set. See reference.md for the full contract, including membership backing and the one-time migration step an account created before this feature shipped owesorg/client.
Create an app context and operate inside it
Goal: give one app (or one customer) its own isolated data partition.
Prerequisites: a root sk_* key (or, to create only, a credential holding
app-contexts:c that is not confined to a single context). Deleting an app context is
root-only — a scoped key or token (ssk_* / st_*) cannot tear down a context, even one
carrying the wildcard * scope. An account (live and test tenants counted separately) can
hold up to 100 app contexts; creating one beyond that returns 402 with the code
SUBSCRIPTION_LIMIT_EXCEEDED. Plan your per-customer context model within that limit.
A context is the hard isolation boundary — all records, documents, folders, and schemas
live inside one. The id must match ^[a-z][a-z0-9-]{2,30}$.
const ctx = await client.auth.createAppContext({
body: {
contextId: 'clinic-intake',
name: 'Clinic Intake App',
description: 'Intake records for the Northside pilot',
},
});
vectros context create clinic-intake --name "Clinic Intake App"
vectros context list
vectros context get clinic-intake
Once the context exists, data written under a credential scoped to it is partitioned there and is unreachable from any other context — the isolation is enforced by the platform, not by your filters.
Tearing a context down is deliberate and irreversible. The delete is a confirm-gated
asynchronous cascade: you must pass a confirm token equal to the contextId, and the
context then drains all of its children in the background.
// Without `confirm` this rejects with 400 and touches nothing.
await client.auth.deleteAppContext({ contextId: 'clinic-intake', confirm: 'clinic-intake' });
// The context flips to `purging` immediately, reaching `deleted` once the drain completes.
# The CLI equivalent asks you to re-type the context id before doing anything;
# --force skips the prompt (required in scripts, where there is no terminal).
vectros context destroy clinic-intake
The dashboard's Contexts page offers the same teardown behind a typed confirmation dialog. All three paths run the identical confirm-gated cascade on the server.
Define a role and grant a principal access to a context
Goal: create a reusable, identity-agnostic permission shape and bind a principal to it inside a context.
Prerequisites: an existing context; a principal id (usr_<userId> or key_<keyId>).
A role is defined once and reused; an access profile binds a principal to either a
role or inline scopes. Always author explicit resource:op action forms.
# A reusable read-only role in the context.
vectros role create --context clinic-intake \
--role-id intake-reader --name "Intake Reader" \
--actions records:r,search:r
# Bind a user principal to that role (the binding is a separate step from issuing a key).
vectros access grant --principal usr_<userId> --context clinic-intake --role intake-reader
# Or bind inline single-clause scopes without a named role (CLI 0.25.0 and later):
vectros access grant --principal usr_<userId> --context clinic-intake --actions records:r,search:r
# Grant yourself access (the signed-in user), in the test tenant:
vectros access grant --principal me --context clinic-intake --role intake-reader --tenant test
me is resolved per tenant. In the test tenant your principal has a different id from your live user, so me resolves it per tenant: add --tenant test and it still works, as above. That is also why a usr_<id> copied from your live tenant is refused in the test tenant. This needs CLI 0.25.0 or later and platform 0.47.0 or later (which adds GET /developer/me?tenant=); on an earlier platform the command typically stops and points you to vectros identity list-all --tenant test (an owner login), which shows the id to pass as --principal usr_<id>.
The same through the SDK, using inline scopes (the wire form is snake_case allowed_actions):
await client.auth.createAccessProfile({
contextId: 'clinic-intake',
body: {
principalId: 'usr_<userId>',
scopes: [{ allowed_actions: ['records:r', 'search:r'] }],
status: 'active',
},
});
Expected result: the profile is created (or, on a repeat, the existing one is returned
unchanged). A profile carries exactly one of scopes or roleId — set one and the
other is cleared. Binding to a roleId that doesn't exist in the context is rejected with
400 naming it, rather than being stored as a profile that could never authenticate. To see
the contexts a principal is bound to: vectros access list --principal usr_<userId>. The CLI's token is pinned to
the default context, so depending on the caller a binding in another context may not appear in that list (the
command says so on standard error from CLI 0.26.0); check one context with
vectros access get --principal usr_<userId> --context <context-id>.
A profile-create takes
scopes(a list of inline clauses) orroleIds, not both. For clauses several profiles share, define a role (in a blueprint) and reference it byroleIds.
Invite a sub-user by email
Goal: bring a person into a context without creating their user record and access profile yourself — let them complete onboarding.
Prerequisites: an existing context; either an existing roleId in it, or the inline
scopes you'd give a standalone access profile.
const invite = await client.auth.createInvite({
email: 'newhire@example.com',
contextId: 'clinic-intake',
accessProfile: { roleId: 'intake-reader' }, // or: { scopes: [{ allowed_actions: [...] }] }
acceptUrl: 'https://my-app.com/accept', // required unless sendEmail is false
});
// → { userId, inviteExpiresAt, emailSent: true }
acceptUrl is validated whenever you supply it, including with sendEmail: false: it must be
an https:// URL whose host is a domain name (an IP-literal host is rejected), and a
custom-scheme deep link is a 400.
To deliver the invitation yourself instead of through Vectros's email, set sendEmail: false —
the response then carries the raw token and a ready-made accept link:
const invite = await client.auth.createInvite({
email: 'newhire@example.com',
contextId: 'clinic-intake',
accessProfile: { roleId: 'intake-reader' },
sendEmail: false,
});
// → { userId, inviteExpiresAt, emailSent: false, inviteToken, acceptLink }
Expected result: a PENDING user exists with its access profile already bound — unusable
until accepted. Re-inviting the same email+contextId rotates the token and resends rather
than duplicating — unless your credential lacks users:r+users:u, in which case the
collision itself returns a 409 instead of silently resending. A 400 names the reason if
roleId doesn't exist in the context, acceptUrl isn't an https URL, or ttlSeconds (default
7 days, 1 hour–30 days) is out of range. A 403 means the invite's resolved permissions exceed
your own credential's scope. A 409 otherwise means the email already belongs to an
active/suspended member of THIS SAME context, already has a PENDING invitation here without your
credential holding users:r+users:u to resend it, or already resolves to a SUSPENDED member of
a different context in this same tenant (a deliberate lockout, never silently attached) — with a
scoped credential (ssk_*/st_*) these causes all return the identical, undifferentiated
409; only a root API key still gets the structured email_already_associated body for the
cross-context-SUSPENDED cause. Treat any 409 from this endpoint as "address unavailable within
this tenant" unless you're calling with a root key. An email that already resolves to an
ACTIVE or PENDING member of a different context in this same tenant grants/attaches access to
this context instead of 409ing — provided your credential holds the scope that grant/attach
itself needs (users:r for ACTIVE, users:r+users:u for PENDING; see
identity-access/reference.md for the exact
dispatch) — without it, this 409s too, same undifferentiated shape as the causes above. An email
that already has an identity in your OTHER tenant (test vs. live) is not a 409 — it creates a
second, independent membership there.
The invitee accepts it themselves — typically from your acceptUrl landing page, after they
authenticate with your own login system:
await client.identity.updateUser({
id: invite.userId,
body: {
status: 'ACTIVE',
inviteToken: '<token from the accept link>',
externalSubject: '<their id in your auth system>',
emailVerifiedAttestation: true, // your attestation that YOU verified their email
},
});
// The user flips PENDING → ACTIVE. `email` is editable again from this point.
This call does not, by itself, let the invitee sign in to anything. Calling
updateUseryourself (server-to-server, with your own auth system's identifier) activates the user and recordsexternalSubject, but it grants no sign-in — not to the Vectros dashboards, and not via token exchange. If the invitee needs to sign in themselves through token exchange, have them presentinviteTokenthere directly with their own credential instead of callingupdateUseron their behalf — Vectros verifies it and completes the same activation. A subject stored withupdateUseralso does not make the person a member of your account (it is ignored for the tenant claims in sign-in tokens, the memberships list, switching the active tenant, and an ownership transfer). To give such a person access, delete the user and invite them again; accepting the invitation binds the subject and counts it. See Inviting a sub-user by email for the full picture.
While the invitation is outstanding: email cannot be changed by editing the user directly
— delete the pending user and re-invite to redirect it. Resending needs more than creating did,
and takes the same request shape as creating — accessProfile and (unless sendEmail: false)
acceptUrl are still required by the type, even though a resend cannot change the invitee's
already-bound permissions:
await client.auth.resendInvite({
email: 'newhire@example.com',
contextId: 'clinic-intake',
accessProfile: { roleId: 'intake-reader' }, // required by the type; ignored — permissions don't change
acceptUrl: 'https://my-app.com/accept', // required unless sendEmail is false
});
// Rotates the token, extends its expiry, and invalidates the previous accept link.
// Requires users:r and users:u in addition to the users:c that creating an invite needs.
If the invitation changed while it was being resent (another resend or an edit), the call
returns 409 and writes nothing: re-read the invitation and retry. If it was deleted or already accepted, the
call returns 404.
Mint a least-privilege scoped key (ssk_*)
Goal: issue a permanent, identity-bearing credential that can never exceed a profile — the right shape for an agent or a bot.
Prerequisites: a principal that already has an access profile in the target context
(the previous guide). The key inherits that profile and cannot exceed it. Minting also
requires the caller to hold the identity the bound profile carries — issuing a key on behalf
of a principal whose identity you don't hold is rejected with 403 (a root key is exempt).
# Issue an ssk_* for the bound principal. The raw secret is shown ONCE.
vectros key issue --principal usr_<userId> --context clinic-intake --name agent-key --format env
# → VECTROS_API_KEY=ssk_live_...
--format env prints VECTROS_API_KEY=ssk_live_… so you can drop it straight into an
agent's environment. Other formats: human (a labeled block with the secret), raw (just
the secret), json.
Expected result: the command prints the new key id, its binding, and the raw ssk_*
once. There is no way to re-read a key's secret. If you lose it — or want to rotate —
revoke and re-issue:
vectros key rotate --principal usr_<userId> --context clinic-intake --name agent-key --format env
vectros key list --context clinic-intake
vectros key revoke <keyId> # stops working within ~5 minutes (authorizer cache)
The key authenticates as its bound principal: every call it makes is attributed to that identity, and it is confined to that principal's profile.
Issuing a key against a profile or a user that is suspended is refused with 409: reactivate it
first. A key bound to the account owner's own principal acts as the owner (it may change the owner's
user and access profile), unless another member minted it on the owner's behalf with
delegate-mint; such a delegated key never counts as the owner.
Mint a short-lived token (st_*) and the front-end-safe pattern
Goal: hand a browser a narrowed, short-lived credential without ever exposing a root key.
Prerequisites: a backend holding an sk_* root key. Minting an st_* is a root-key
operation; a scoped key (ssk_*) gets a 403 from the mint endpoint.
Mint an st_* scoped to exactly one user's data. The token carries its scope internally and
cannot widen it.
// On your backend, in your login handler — NEVER in browser code.
const minted = await client.auth.mintToken({
scope: {
allowedActions: ['records:r', 'search:r'],
dataScope: { userId: ['<that user\'s id>'] }, // narrow to one user's data
},
// expiresInSeconds defaults to 3600 (1h), which is also the maximum.
});
// → { token: "st_...", expiresAt: <unix-seconds> }
Hand minted.token to the browser. The browser constructs its own client with that token
and calls Vectros directly:
// In the browser, with the st_* received from your backend:
const browserClient = new VectrosClient({
token: minted.token,
environment: 'https://api.vectros.ai',
});
// A scoped token must name the same user in the request: strict scope rejects a list
// without the matching filter.
const myRecords = await browserClient.records.listRecords({
type: 'intake_form',
userId: '<the user id from the mint call>',
});
Expected result: only the minted token goes to the browser, not the root key; the browser's token is confined to one user for at most its lifetime; if the browser is compromised, blast radius is one user for one token-lifetime. The token cannot be revoked in flight — keep the lifetime short.
The mint endpoint accepts one scope clause per request. For a compound shape, bind the principal to a multi-clause role and mint via the scoped-key path instead.
Register a trusted external IdP issuer and exchange its token
Goal: let your own identity provider mint Vectros-scoped tokens for your users directly —
register the IdP once, then trade its JWTs for st_* tokens with no backend of yours in the
request path.
Prerequisites: a root sk_* key (or the CLI bootstrap's provisioning capability) to
register; an existing app context; an IdP that issues JWTs and publishes a JWKS endpoint.
// Register the issuer once. issuerId is your own slug for it; issuer/jwksUri/audience come
// straight from your IdP's own configuration.
const issuer = await client.auth.registerIssuer({
issuerId: 'auth0-prod',
issuer: 'https://your-tenant.us.auth0.com/',
jwksUri: 'https://your-tenant.us.auth0.com/.well-known/jwks.json',
audience: 'https://api.your-app.example.com',
contextId: 'clinic-intake',
});
// → { issuerId: 'auth0-prod', created: true, status: 'pending_verification',
// verificationClaim: 'https://vectros.ai/claims/issuer_challenge',
// verificationNonce: 'hB1v0x…', verificationExpiresAt: '2026-09-27T09:30:00Z', ... }
A new registration is pending_verification, and accepts no tokens until you prove you control the
IdP (0.45.0+). Anyone holding a root key can name any issuer URL and audience, so registering alone
proves nothing; verification is what activates it. (A registration scoped with restrictedToDomain to a domain you have already
verified is active at once: it routes only tokens whose hd claim is that domain, so it can only ever
serve your own domain's users — it proves you control the domain, not the issuer.)
-
In your IdP, add an admin-controlled rule that stamps the returned
verificationNonceinto theverificationClaimclaim of the tokens it issues. Never map the claim from an attribute your end users can edit. For Auth0, a post-login Action, with the nonce stored as an Action secret namedVECTROS_ISSUER_NONCE:exports.onExecutePostLogin = async (event, api) => { const claim = 'https://vectros.ai/claims/issuer_challenge'; api.idToken.setCustomClaim(claim, event.secrets.VECTROS_ISSUER_NONCE); api.accessToken.setCustomClaim(claim, event.secrets.VECTROS_ISSUER_NONCE); };Deploy the Action, then add it to the post-login flow (Actions → Triggers → post-login, then Apply); a deployed Action that is not in the flow never runs. Actions apply to the whole flow, so to limit this one to a single application, return early when
event.client.client_idis not that application's. (Okta inline hooks, Entra claims-mapping policies and Keycloak protocol mappers work the same way.) -
Sign in once through that IdP, after the rule is in place (a token from an earlier login lacks the claim), and send the resulting JWT to the verify call. Either token type works, ID token or access token, provided its
audis the registration'saudience: an Auth0 ID token's audience is the application's client id, an access token's is the API identifier.await client.auth.verifyIssuer({ issuerId: 'auth0-prod', token: aJwtFromThatLogin }); // → { issuerId: 'auth0-prod', status: 'active', ... }The token is checked and discarded, never stored. It must verify against the key set your issuer publishes in its own OpenID Connect discovery document (
<issuer>/.well-known/openid-configuration), and thejwksUriyou registered must be exactly that document'sjwks_uri. An issuer that publishes no discovery document, or an IdP with no way to add a claim (for example, raw "Sign in with Google" for personal accounts), cannot be verified this way.
The challenge expires after 7 days; an expired registration can't be verified — delete it and register
again (the new registration has a new verificationNonce, so update the rule's secret to match). The rule can
be removed once the registration is active.
If verify is refused, the message names the check that failed. The common 400s:
- "does not carry the … claim" or "claim must be a string": the rule is not deployed and attached, its secret is unset, or the token came from a login made before it was; or the rule sets something other than a string. Sign in again.
- "claim does not match this registration's verificationNonce": the claim carries a wrong or stale value, typically the nonce of an earlier registration.
- "not issued for this registration's issuer" or "audience does not include": the token is for a
different issuer or audience than the registration. Send the token whose
audis the registration'saudience: with Auth0 that is the access token when the audience is your API identifier, and the ID token when it is the application's client id. - "'token' is required" or "'token' must be a JWT": the value is missing or is not a signed, compact JWT. An opaque access token can't be used; configure the IdP to issue a JWT for the audience.
- "could not be verified against the issuer's key set": the signature, expiry, issuer or audience check failed, or the signing key could not be found or fetched. Sign in again for a fresh token.
- "discovery document could not be fetched", "must use the https:// scheme", "names a different
issuer" or "jwksUri does not match the jwks_uri this issuer publishes": the issuer's discovery
document must be reachable over https, name exactly the registered issuer, and publish exactly the
registered
jwksUri. Delete the registration and register it again with the published values. - "verification challenge has expired": delete the registration and register it again.
- "already registered by another registration": another registration holds the
(issuer, audience)pair. Give this one its ownaudience. - "already has an active issuer registered" or "does not name an existing app context": an app context may have exactly one active IdP, and it must exist. Deregister the existing one, or create the context.
- "not awaiting verification": the registration is no longer
pending_verification. It is active or suspended, it was registered before verification existed, or its challenge changed or expired while your request was running. Read it back (getIssuer) to see which.
Other statuses: 403 means the caller lacks a root key or the provisioning capability; 404 means no
registration with that issuerId is visible to you; 409 means the registration was changed or removed
while it was being verified and nothing was activated. A timeout or 5xx says nothing about whether the
platform finished, so read the registration back before retrying: a retry of a verify that did succeed
answers "not awaiting verification".
Until verify succeeds, a token exchange against the registration answers 404, the same as for an issuer that was never registered.
Alternative: register scoped to a domain you own (0.44.0+). If everyone who will sign in through this
IdP is on a company domain you have verified, and the IdP puts that domain in an hd claim (Google does for
Workspace accounts; other IdPs need a claims-mapping rule that emits a claim literally named hd), register
with restrictedToDomain instead. There is no challenge step: the registration is active straight away,
and it only ever accepts tokens whose hd claim equals that domain.
const scoped = await client.auth.registerIssuer({
issuerId: 'workspace-prod',
issuer: 'https://accounts.google.com',
jwksUri: 'https://www.googleapis.com/oauth2/v3/certs',
audience: 'your-client-id.apps.googleusercontent.com',
contextId: 'clinic-intake',
restrictedToDomain: 'acmecorp.com',
});
// → { issuerId: 'workspace-prod', created: true, status: 'active', restrictedToDomain: 'acmecorp.com', ... }
The domain has to be verified for your account first. Your account owner does that in the developer portal
under Domains (the same place webhook domains are verified), or with vectros domains register,
vectros domains verify <id>, vectros domains list and vectros domains delete <id> (@vectros-ai/cli
0.24.0 or later, signed in as the owner) — the API key that makes this call can't do it. If it hasn't been, the register call is refused with 400:
{ "message": "restrictedToDomain 'acmecorp.com' is not a VERIFIED domain for your account. Your account owner must verify ownership first via the developer portal ..." }
Verify the domain, then repeat the call. A second registration for the same (issuer, audience) and the
same domain is also refused with 400 — give each environment or context that shares an IdP account its
own audience. A token without an hd claim is never accepted by a domain-scoped registration. To change
the domain later use updateIssuer — clearing it (restrictedToDomain: "") is refused unless the
registration holds the unrestricted (issuer, audience) pair, which one created scoped to a domain never did
(see the
reference).
To get an unrestricted issuer from a domain-scoped one, delete the scoped registration, register a new
one without restrictedToDomain, and verify it (see above). A context holds one active issuer, and the delete
is refused once any user has been created or matched through the old issuer; in that case register the new
issuer under a different app context.
Re-registering the same issuerId is idempotent — it returns the existing registration
unchanged (created: false), not an error. Register through the SDK/API directly, with the CLI
(vectros issuers register, then vectros issuers verify <issuerId> --context <ctx> --idp-token-file <path>,
@vectros-ai/cli 0.23.0 or later), or declare issuers: in a
blueprint and let vectros blueprint apply (or vectros bootstrap) provision it; either ends its
output with the challenge and the verify command when a registration is pending.
Exchange a token. This is the one call in this guide that carries no Vectros credential at
all — the subject_token from your own IdP is the credential:
const resp = await fetch('https://api.vectros.ai/v1/auth/token/exchange', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
subject_token: idpIssuedJwt, // the JWT your IdP just handed this user
subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
}),
});
if (!resp.ok) {
const { error, error_description } = await resp.json();
throw new Error(`token exchange failed: ${resp.status} ${error} ${error_description}`);
}
const { access_token, expires_in } = await resp.json();
// access_token is an st_* token — use it exactly like any other.
const scoped = new VectrosClient({ token: access_token, environment: 'https://api.vectros.ai' });
First-time subjects need a binding path — pass exactly one:
// A subject with a pending invite (see "Invite a sub-user by email" above):
body: JSON.stringify({ /* ...as above... */, invite_token: 'inv_...' })
// A subject with no invite, against an issuer that declared selfSignupPolicies:
body: JSON.stringify({ /* ...as above... */, signup_type: 'practitioner' })
Expected result: a subject with an existing Vectros identity, a valid invite_token, or a
matching signup_type gets back { access_token: "st_...", token_type: "Bearer", expires_in: 3600 }. Every other case — bad signature, expired token, unregistered issuer, no binding path
applies — returns the OAuth error shape ({"error": ..., "error_description": ...}) with a fixed
generic message that does not say which check failed (the status still differs: 404 no matching
registration, 401 the token failed verification, 403 no binding path applies). A request body
over 8 KB is 413, and a body that is not valid JSON is 400. If
you're building a browser SPA against Auth0, @vectros-ai/react's Auth0AuthProvider already
wraps this exact call (exchangeToken/mintPartnerApiToken) — wire its config to your Auth0
application and this endpoint instead of writing the fetch yourself.
Clean up. Deregistering is refused if the issuer has ever bound a user — deactivate affected users first, or replace the issuer, rather than silently orphaning their access:
await client.auth.deleteIssuer({ issuerId: 'auth0-prod' });
// 409 if any user was ever created or matched via this issuer.
See reference.md for the full field grammar, every
error code, the one-active-issuer-per-context rule, and the context_id disambiguator for an
issuer registered against more than one context.
Restrict a credential to one customer's data with dataScope
Goal: confine reads and searches to a single org's (or client's) records, including the strict-scope rules.
Prerequisites: records tagged with a scopes entry (e.g. org:<id>) you can scope to.
dataScope is enforced as a server-side filter below any filter the caller supplies. It is
strict: a scoped call must include the matching filter explicitly. userId is its own
fixed dimension; every other dimension is a namespace, keyed scope:<namespace> in
dataScope.
// Mint a token confined to one org. `orgId` is a Vectros org entity id — see
// "Create identity entities and a user" above for how to create one.
const orgId = '<org id>';
const minted = await client.auth.mintToken({
scope: {
allowedActions: ['records:r', 'search:r'],
dataScope: { 'scope:org': [orgId] },
},
});
const scoped = new VectrosClient({ token: minted.token, environment: 'https://api.vectros.ai' });
// The call MUST carry the matching scope filter — strict scope requires it explicitly.
const list = await scoped.records.listRecords({ type: 'intake_form', scope: `org:${orgId}` });
// Only org-tagged records come back; tenant-only (unowned) records are filtered out.
const hits = await scoped.search.content({
query: 'follow-up appointment',
mode: 'TEXT',
limit: 100,
scope: `org:${orgId}`,
});
Expected result: the credential sees only rows owned by that org. Omitting the scope
filter on the call is rejected with a 403. To also
reach tenant-level (owner-less) records under the same credential, opt in explicitly
with a null in the value list at mint time: dataScope: { 'scope:org': ['<org id>', null] }.
The null is never implied.
The same pattern works for any registered namespace (scope:team, scope:client, …) —
substitute the dimension on both the mint and the call. ?scope= takes one entry per
list query; pair it with ?userId= when you need both dimensions on the same call (search takes
scopeFilters, one entry per namespace).
A dimension your dataScope never names isn't just unnarrowed on reads — it's also a
dimension you have no way to write into. If a role instead of a single mint needs to
cover a dimension for every principal it's bound to without enumerating values, its clause
can use the ${{ any }}, ${{ under.self.* }}, or "*" default-dimension placeholder forms
— see reference.md.
Verify what a credential actually is
Goal: confirm the principal, tenant, and scope a credential resolves to.
A lightweight identity-binding check returns the authenticated principal's shape:
const who = await client.auth.ping();
// For an sk_* root key: principalType 'root_key' (no action list — it's wildcard).
// For an ssk_* scoped key: principalType 'scoped_key' + its allowedActions.
// For an st_* token: principalType 'token' + tokenExpiresAt.
// dataScope.scopes reports the resolved scope:<namespace> bindings, if any.
This is the fastest way to confirm a freshly minted scoped key carries the actions you expect before you ship it. An invalid credential is denied at the edge with a 403.
Where to go next
- reference.md — every identity/access method, the full scope grammar, the data-plane allowlist, error codes, and a "notes & limits."
- explanation.md — the why behind contexts, namespaces, scopes, profiles, and the three credential types.
- The blueprint walkthroughs (getting-started, clinical-intake, agentic-sdlc, second-brain) — end-to-end builds that provision a context, principal, profile, and scoped key in one command.
- The generated API reference (rendered from the OpenAPI specification) — canonical request and response shapes.