Auth API
v0.2.0Users, sessions, signing keys, groups, delegation, account deployment.
152 operationsBase URL:
https://auth.yieldfabric.comAuth
Sign-in flows, token lifecycle, MCP login. Both public (login, provider-exchange) and authenticated (refresh, logout) endpoints live here. See [guides/authentication.md](guides/authentication.md).
- postEmail + password login
/auth/login - postLogin + mint a token scoped to specific service audiences
/auth/login/with-services - postRevoke the current refresh token (single device)
/auth/logout - postRevoke every refresh token for the current user
/auth/logout-all - postMint an MCP token from an already-authenticated session
/auth/mcp/generate-token - postLogin from an MCP host with optional impersonation
/auth/mcp/login - postRotate access + refresh tokens
/auth/refresh - getList public keys that can sign you in
/auth/users/me/login-keys - postIssue a WebAuthn challenge
/auth/webauthn/challenge - postExchange a WebAuthn assertion for a JWT
/auth/webauthn/exchange - getHTML login form for MCP browser-based flows
/mcp/login
Identity providers
Pluggable identity-provider exchange flows: Averer, MetaMask, Email/OTP, WebAuthn. Public configuration plus `/auth/{provider}/exchange`, `/auth/{provider}/link`, `/auth/{provider}/unlink`. See [guides/identity-providers.md](guides/identity-providers.md).
- postSign-in / sign-up via an identity provider
/auth/{provider}/exchange - postLink an additional provider identity to the current user
/auth/{provider}/link - postUnlink a provider identity from the current user
/auth/{provider}/unlink - getPublic chain-config snapshot for the frontend
/auth/chain-config - getPublic identity-provider chooser config
/auth/providers/config
Users
User CRUD, profile, email change, account lockdown, login-key discovery. Role and deactivation operations require admin permissions.
- postChange the current user's password
/auth/change-password - postCreate a new user
/auth/users - postDeactivate a user (admin only)
/auth/users/{user_id}/deactivate - putChange a user's role (admin only)
/auth/users/{user_id}/role - getGet the current user's profile
/auth/users/me - patchChange the current user's email (B6/B9)
/auth/users/me/email - getGet current email verification state
/auth/users/me/email/verification - postConfirm an email verification code
/auth/users/me/email/verification/confirm - postSend an email verification code
/auth/users/me/email/verification/start - getGet the current user's account-lockdown status
/auth/users/me/lockdown - postCancel a pending lockdown request
/auth/users/me/lockdown/cancel - postExecute lockdown after cooldown
/auth/users/me/lockdown/execute - postFinalize an executed lockdown
/auth/users/me/lockdown/finalize - postOpen a lockdown request (start the 24h cooldown)
/auth/users/me/lockdown/request - getGet the current user's extended profile (B5)
/auth/users/me/profile - patchPartially update the current user's extended profile
/auth/users/me/profile - postUpload the current user's profile photo
/auth/users/me/profile/avatar - deleteRemove the current user's uploaded profile photo
/auth/users/me/profile/avatar
Permissions
Per-user permission grant / revoke / replace / check. Granular RBAC on top of the six built-in roles.
- getList a user's granted permissions
/auth/users/{user_id}/permissions - postAdd permissions to a user (additive)
/auth/users/{user_id}/permissions - putReplace the user's entire permission set
/auth/users/{user_id}/permissions - deleteRemove permissions from a user (subtractive)
/auth/users/{user_id}/permissions - getCheck whether a user has a specific permission
/auth/users/{user_id}/permissions/{permission} - postGrant a single permission
/auth/users/{user_id}/permissions/{permission} - deleteRevoke a single permission
/auth/users/{user_id}/permissions/{permission}
Signatures
Wallet-signature authentication + signature-key registration and management. See [guides/signatures.md](guides/signatures.md).
- postWallet-signature authentication (legacy path)
/auth/signature - getList the current user's signature keys
/auth/signature/keys - getGet a specific signature key
/auth/signature/keys/{key_id} - deleteDelete (deactivate) a signature key
/auth/signature/keys/{key_id} - getIssue a one-time nonce for signature sign-in
/auth/signature/nonce - postRegister a new public key for the current user
/auth/signature/register - postSign-in via a registered wallet signature
/auth/signature/signin
API keys
API-key authentication + management. Alternative to JWT for non-interactive callers. See [guides/api-keys.md](guides/api-keys.md).
- postAuthenticate with an API key
/auth/api-key - postGenerate a new API key for the current user
/auth/api-key/generate - getList the current user's API keys (metadata only)
/auth/api-keys - getGet a specific API key (metadata only)
/auth/api-keys/{key_id} - postRevoke an API key (irreversible)
/auth/api-keys/{key_id}/revoke
Groups
Group CRUD, members, group keypairs, entity scope, audit logs, on-chain account members/owners. See [guides/groups.md](guides/groups.md).
- getList all groups (SuperAdmin scope)
/auth/groups - postCreate a new group
/auth/groups - getGet a group by ID
/auth/groups/{id} - putUpdate group metadata
/auth/groups/{id} - deleteDelete a group (owner only)
/auth/groups/{id} - getList account members (NFT- and address-gated)
/auth/groups/{id}/account-members - getList on-chain owners of the group's account
/auth/groups/{id}/account-owners - getGroup on-chain account status
/auth/groups/{id}/account-status - postAdd an NFT- or address-gated account member
/auth/groups/{id}/add-account-member - postRegister a new owner on the group's on-chain account
/auth/groups/{id}/add-owner - getRead the group's audit log
/auth/groups/{id}/audit-logs - postDeploy the group's first on-chain account
/auth/groups/{id}/deploy-account - postDeploy an additional wallet for an existing group
/auth/groups/{id}/deploy-wallet-account - getList the group's entity scope
/auth/groups/{id}/entity-scope - postAdd entries to the group's entity scope
/auth/groups/{id}/entity-scope - getList a group's keypairs
/auth/groups/{id}/keypairs - postCreate a new group keypair
/auth/groups/{id}/keypairs - getList group members
/auth/groups/{id}/members - postAdd a user to a group with a role
/auth/groups/{id}/members - putChange a member's role
/auth/groups/{id}/members/{user_id} - deleteRemove a user from a group
/auth/groups/{id}/members/{user_id} - postRemove an account member
/auth/groups/{id}/remove-account-member - postRemove an owner from the group's on-chain account
/auth/groups/{id}/remove-owner - getList groups the current user is a member of
/auth/groups/user
Delegation
Delegation tokens + on-demand delegation JWT minting. Lets a user act on behalf of a group with a scoped permission set. See [guides/delegation.md](guides/delegation.md).
Keys
Server-custodied key management (encryption keys, signing keys), per-key encrypt/decrypt/sign/verify operations, and vault-side key operations used by sister services.
- postDecrypt a payload with the caller's encryption keypair
/api/v1/decrypt - postEncrypt a payload with a registered keypair
/api/v1/encrypt - postGenerate an encryption keypair for a contact id
/api/v1/generate-keypair - getGet metadata about a specific key
/api/v1/keys/{key_id}/info - getGet a contact's public key by hashed contact id
/api/v1/public-key/{contact_id} - postSign data with the caller's signing keypair
/api/v1/sign - postDerive a deterministic private salt for a vault account context
/api/v1/vault/create-salt - postDecrypt a vault payload on behalf of the caller's wallet
/api/v1/vault/decrypt - postSign a vault meta-transaction on behalf of the caller's wallet
/api/v1/vault/sign - postVerify a signature against a registered public key
/api/v1/verify - postCreate a new server-custodied keypair for the current user
/keys/ - getGet a specific keypair (public fields only)
/keys/{key_id} - putUpdate keypair metadata (name, metadata blob)
/keys/{key_id} - deleteDeactivate a keypair (soft-delete)
/keys/{key_id} - postBegin a keypair rotation (off-chain only)
/keys/{key_id}/rotate - postPropagate a key rotation to on-chain accounts
/keys/{key_id}/rotate-on-chain - postCancel an in-progress rotation
/keys/{key_id}/rotation/cancel - postFinalize a rotation (swap active flags)
/keys/{key_id}/rotation/finalize - getCheck whether the key is registered as an owner of the user's wallets on-chain
/keys/{key_id}/wallet-status - postRegister an external (wallet-held) key for the current user
/keys/external - postProve ownership of an external key via signature
/keys/external/verify-ownership - getRead the key-operation audit log
/keys/logs - getIdentity-provider health probe
/keys/providers/health - postRegister the user's active key as an owner of a specific wallet address
/keys/register-with-specific-wallet - postRegister the user's active key as an owner of their default wallet
/keys/register-with-wallet - postRemove the user's active key as an owner of a specific wallet
/keys/unregister-from-specific-wallet - getGet a user's active default keypair
/keys/users/{user_id}/default-key - getList a user's keypairs (admin / self)
/keys/users/{user_id}/keys
Accounts
On-chain account deployment for users and groups, default-chain management. See [guides/account-deployment.md](guides/account-deployment.md).
- postDeploy an on-chain account for an arbitrary entity
/auth/deploy-account - postDeploy the first on-chain account for a specific user
/auth/users/{user_id}/deploy-account - getList an entity's deployed accounts across chains
/entities/{entity_type}/{entity_id}/chain-accounts - postSwitch an entity's default chain
/entities/{entity_type}/{entity_id}/default-chain
Verifications
KYC / credential-issuance records and the Sumsub webhook.
Admin
Master-key management, emergency operations, protected validation endpoints, health checks. SuperAdmin role required for `/admin/**` routes.
- postMulti-step emergency recovery from a backup blob
/admin/emergency/recovery - postCancel an in-flight re-encryption sweep
/admin/emergency/reencryption/cancel - postInitiate a system-wide re-encryption sweep
/admin/emergency/reencryption/initiate - getGet progress of an in-flight re-encryption sweep
/admin/emergency/reencryption/progress - postCreate an encrypted backup of the master key
/admin/master-key/backup - postOne-call emergency recovery (sets a new master key from a backup KEK)
/admin/master-key/emergency-recovery - postRotate the master encryption key
/admin/master-key/rotate - getGet master-key health and rotation status
/admin/master-key/status - getService health check
/health - postTrigger refresh-token cleanup
/health/cleanup - getDatabase connectivity check
/health/db - getAPI-key-authenticated probe
/protected/api-key - getHello-world authenticated endpoint
/protected/hello - getValidate a user JWT and return its claims
/protected/jwt - getSignature-authenticated probe
/protected/signature - getUnified authentication probe
/protected/unified
Connections
Entity-to-entity connections: requests, sharing preferences, notifications. See [paths/connections.yaml](paths/connections.yaml).
- getList connection-related notifications for the current user
/auth/connections/notifications - postMark a notification as read
/auth/connections/notifications/{id}/read - postSend a connection request to another entity
/auth/connections/request - getList the current user's connection requests (sent + received)
/auth/connections/requests - getGet a specific connection request
/auth/connections/requests/{id} - postAccept a connection request
/auth/connections/requests/{id}/accept - postBlock a connection request (rejects + prevents further requests from the sender)
/auth/connections/requests/{id}/block - getGet sharing preferences for a connection
/auth/connections/requests/{id}/preferences - postSet sharing preferences for an accepted connection
/auth/connections/requests/{id}/preferences - postReject a connection request
/auth/connections/requests/{id}/reject
Invitations
Unified invitation framework — magic-link invites to become a user and execute a typed target action (none | obligation | deal_flow | group_join | connection). Supersedes /auth/connections/invite*. See [paths/invitations.yaml](paths/invitations.yaml).
- getList invitations the current user has sent
/auth/invitations - postCreate an invitation and send the magic-link email
/auth/invitations - getLook up an invitation by token (public, redacted)
/auth/invitations/{token} - deleteSoft-revoke an invitation by token (inviter only)
/auth/invitations/{token} - postAccept an invitation and resolve the next action
/auth/invitations/{token}/accept - postResend the invitation email (inviter only, rate-limited)
/auth/invitations/{token}/resend - getList live invitations addressed to the current user's email
/auth/invitations/received
GraphQL
Federated identity subgraph at `/graphql/identity`. The SDL endpoint at `/graphql/identity/sdl` is unauthenticated (Apollo Router compose needs it); the data endpoint is JWT-gated.