All docsEnterprise demoTOKENLOCK
Enterprise access controls
Zero-trust access for teams, vendors and AI agents: registered signing keys, scoped permissions, instant revocation and an audit trail of every decision.
How it works
For teams, vendors and AI agents, a site can go from "any holder gets in" to a zero-trust rule, checked on every verify:
approved organization AND registered signing key AND valid entitlement AND permission for this resource AND not revoked
It is off by default. Sites that don't turn it on keep the token-only rule, and existing integrations (gate.js, the PHP drop-in, @proveitonchain/tokenlock 0.1.x, plain REST) keep working unchanged. Registered keys, organizations and scoped permissions are part of Business and Enterprise, and pilot sites we enable on request; the decision log is on every plan. See it end to end in the enterprise demo. This section is also at /docs/enterprise.
- Registered keys. Each key is a wallet address with a label, an owner type (
org,employee,vendororagent), an owner name and email, and an optional organization. Owner details stay offchain, in TOKENLOCK only. - Scoped permissions. Routes (
/app/*for a prefix,/reportsexact,*for all), methods, environments and an expiry. A key with no routes can sign in but reach nothing. - Path and method checks. Send
path,methodand (optional)environmentwith/api/v1/gate/verify. The answer saysallowedwith areasonand carries anaccessobject (key, owner, permissions, expiry). - Instant revocation. Revoking a key, suspending an organization or revoking a token for the site is checked on every verify, so the next request is denied. Responses carry
cache_max_s: 5; don't cache a pass result for longer than that. - Transfer re-approval. If a registered key's token moves away, the key is paused with
pending_approvaland an approval request is queued. A holder whose wallet isn't registered getspending_approvaltoo, and shows up in your open requests. - Agent keys. Short pass lifetimes (15 minutes by default, per key from 60 seconds) and rotation with a grace period: the new key works at once, the old one keeps working until the grace period ends.
Deny reasons: not_registered, pending_approval, key_revoked, key_expired, org_not_approved, org_required, entitlement_revoked, not_holder, route_not_allowed, method_not_allowed, environment_not_allowed, bad_path, lookup_failed.
# Check a pass for one resource
curl -X POST https://proveitonchain.com/api/v1/gate/verify \
-H 'Authorization: Bearer sk_…' -H 'content-type: application/json' \
-d '{"pass":"pp1…","path":"/api/partner/prices","method":"GET","environment":"production"}'
# → { "valid": true, "allowed": true, "correlation_id": "…", "cache_max_s": 5,
# "access": { "mode": "registered_keys", "allowed": true, "reason": "ok", "key": { "id": "key_…", "label": "…", "owner_type": "agent" }, "permissions": { … } } }
# Denied: { "valid": false, "allowed": false, "code": "route_not_allowed", "reason": "This key is not allowed on this route.", … }
Admin API
Manage access from the dashboard (Enterprise access & decision log on each site) or from your server with the site's secret key: Authorization: Bearer sk_… on https://proveitonchain.com/api/v1/tokenlock/access….
GET /access: settings, organizations, keys, open requests, revoked tokens, recent admin actions.POST /access/settings:registered_keys,require_org,agent_pass_ttl_s,default_pass_ttl_s,recheck_holdings_s,decision_webhook,alert_on_abandoned,hash_addresses.POST /access/orgs{ name }or{ id, status: "approved"|"suspended" }.POST /access/keys{ address, label, owner_type, owner_name, owner_email, org_id, routes, methods, environments, expires_at, pass_ttl_s };POST /access/keys/:idto edit;/revoke,/approve,/rotate { new_address, grace_s }.POST /access/requests/:id/approveor/deny;POST /access/entitlements/revokeor/restore{ asset }.
Decision log
Every sign-in ends as one decision: authorized, denied (with the reason) or abandoned (a sign-in request nobody finished before it expired). Denied pass checks are logged too. Each entry has a correlation_id (the sign-in request's nonce, also returned by challenge, sign-in and verify), the reason, key, owner, resource, wallet, hashed IP and timestamps. Kept 14 days on Free, 30 on Starter, 90 on Pro, 180 on Business and 365 on Enterprise.
GET /access/decisions?outcome=denied&reason=…&key_id=…&correlation_id=…&since=…&until=…GET /access/decisions/export?format=csvorformat=jsonl(one JSON event per line).- Decision webhook (Business and Enterprise, opt-in with
decision_webhook): each decision is POSTed asevent: "decision",type: "tokenlock.decision", signed with HMAC-SHA256 inx-tokenlock-signature, same as the alerts above.
Key rotation and short-lived agent sessions
- Add the new key.
POST /access/keys/:id/rotate { "new_address": "bc1q…", "grace_s": 3600 }(or Rotate in the dashboard). The new key gets the same owner, organization, permissions and expiry, and works immediately. Both keys link to each other (rotated_from,rotated_to). - Grace period. The old key keeps working until the grace period ends (default 1 hour, 0 to 7 days; 0 ends it now). Its expiry is moved to the end of the grace period, never later than an expiry it already had.
- The old key expires. After the grace period, sign-ins and pass checks with the old key are denied with
key_expired. A pass never outlives its key: pass lifetimes are capped at the key's expiry. - Agents: short-lived sessions. Agent keys get short passes (15 minutes by default; set
agent_pass_ttl_sfor the site orpass_ttl_sper key, from 60 seconds). The agent signs a fresh one-time message with its key each time, so a leaked pass is only useful briefly, and a rotated or revoked key stops working on the next check.
Token transfers
- Token-only sites (the default): a pass reflects what the wallet held when it signed in. After a transfer, the old wallet's existing pass stays valid until it expires (15 minutes by default, at most 24 hours); its next sign-in is refused, and the new holder can sign in.
- Registered keys: a transfer triggers re-approval. When a registered key's wallet no longer holds the token (checked at sign-in, and on verify at most every
recheck_holdings_s, default 300 seconds), the key is paused withpending_approval, access is denied, and an approval request is queued. The wallet that received the token is not registered, so it also getspending_approvaland appears in your open requests. Nothing is granted until an admin approves. - Permissions and PII stay offchain. Owner names, emails, organizations and permissions live in TOKENLOCK on the key record, not in the token, and our durable backup of them is encrypted. Transferring the token transfers none of them.
- To let a key back in:
POST /access/keys/:id/approve, or approve the request withPOST /access/requests/:id/approve.
Availability and failure behavior
Today, checks depend on our API. This is what happens when part of it is down:
| What is down | Token-only sites | Sites with registered keys |
|---|---|---|
| TOKENLOCK API (your server can't reach us) | Passes can't be checked and new sign-ins can't start. With the PHP drop-in 0.2.0 and @proveitonchain/tokenlock 0.2.0, locked pages fail closed by default: a 503 "try again" answer, the visitor's cookie is kept, and they are back in as soon as we answer. A good answer already in the local cache is reused for up to 60 seconds (token-only) or 5 seconds (registered keys). For low-risk content you can opt in to fail open per integration (failOpen: true in the SDK, 'fail_open' => true in PHP): visitors who already have a pass cookie are let in unverified while we are unreachable. Never use it for admin areas or APIs. SDK 0.1.x sends the visitor to sign in again and clears the cookie. | |
| Blockchain data source (we can't read holdings) | New sign-ins fail closed (lookup_failed). Passes already issued stay valid until they expire, because holdings were checked at sign-in. |
New sign-ins fail closed (lookup_failed). On verify, holdings are cached per wallet for recheck_holdings_s (default 300 seconds). When the cache has lapsed and the lookup fails, passes younger than twice that window stay allowed; older passes are denied with lookup_failed. Revocation, expiry, organization and permission checks don't need the chain and keep working. |
| Access store (our Redis) | Not used for sign-in or verify, so access is unaffected. Decision-log entries during the outage are not recorded. | Fail closed: sign-in and verify answer 503 (kv_unavailable). We never fall back to token-only, so a revoked key never gets through. If stored access settings are lost, they are restored from a durable backup before any access is allowed. |
Revocation is enforced on every verify whenever the access store is reachable, and requests are denied when it isn't.
Roadmap, not available today: Enterprise self-verify (a public spec so your servers check passes, keys and holdings without calling our API), and a second holdings data source for failover. Until then, the behavior above is the current behavior.