# Imajin > identity and authority for AI agents. your agents act as themselves, on your authority, and every action is signed. Imajin is alpha. [Book a demo, or join the alpha as a tester, integrator or partner](https://imajin.ai/alpha); this is not self-serve onboarding. Point your agent at it: start with this guide and the service specs below. Every action is a signed event that anyone can verify, including a third party's own agent. Cost and credit are recorded per identity, and .fair turns that into who gets paid. ## What Imajin is The kernel serves six primitives: **Attestation · Communication · Attribution · Settlement · Discovery · Revocation**. Identity is the subject of those primitives, not an additional primitive. The kernel supplies shared rails for authenticating actors, checking authority and recording outcomes. The kernel hosts shared identity, profile, connection, communication, media, payment and operational services. Apps built on Imajin have their own identities, codebases and deployment responsibilities. They integrate through public scoped contracts, not imports from kernel source or SQL against another service's tables. The app template and registered-app contract describe that boundary. Broker-agent and corpus are internal services with their own runbooks; their presence in this repository does not make them registered vertical apps. The canonical node origin used in the links below is `https://jin.imajin.ai`. A self-hosted node has its own origin and configuration. Service specs describe contracts, not a claim that a service is deployed, publicly accessible or authorized for a caller. The repository is source-available under the [Imajin Network License](https://github.com/ima-jin/imajin-ai/blob/main/LICENSE.md). ## Key concepts Imajin records proof of history, not proof of work. A signature establishes that a particular key signed particular bytes. It does not establish that an assertion is true. An actor-key signature, a node-witnessed record and an unsigned operational log have different evidentiary strength. An integration should preserve that distinction rather than calling every recorded action a user signature. ### Identity and DIDs People, agents, devices, families, communities and businesses are not one interchangeable account. Identity has a scope and, where applicable, a subtype. Key-backed registration derives a `did:imajin:` identifier from the base58-encoded public-key bytes and verifies an Ed25519 signature. DFOS linking is separate and optional; a DID does not itself prove external chain verification. Soft identities do not have an actor signing key. The standing tiers are soft, preliminary, established, steward and operator. A tier is one input to route authorization, not an unrestricted capability or a universal portable reputation score. Read the auth contract for the registration, verified onboarding and authentication flow appropriate to your caller. Soft identity resolution does not by itself establish a browser session. A human session and the identity the human is acting for are separate. `x-acting-as` selects an organization or business context. The server checks live membership, role and the controller's allowed services before using that DID for ownership or attribution. Use the verified effective identity for names, handles, defaults and labels as well as authorization. Never substitute the personal DID when an organization action is refused. Agent delegation is distinct from human organization act-as. An agent proves its own identity and acts under the principal's authority. A relationship showing whom the agent serves is not sufficient evidence that a particular capability is permitted. The auth and service contracts define the grants, expiry, revocation and compatibility checks applied to each operation. ### Attestation, disclosure and revocation Attestations bind a statement to its issuer and subject. Mechanical attestations can be node-signed on behalf of an authenticated action; they do not imply possession of the human's or organization's private key. Consumers should check the recorded proof model rather than inferring it from a DID or display label. Private documents and legal-entity data have their own disclosure policies. A broad media permission does not reveal sealed bank identifiers or authorize every legal-entity field. Consumer reads use the dedicated disclosure helpers and current consent, not copied metadata. Document signatures bind the documented content payload; do not infer request-specific consent unless the signed bytes actually bind that request. Revocation changes active authority while retaining its provenance. Signed tombstones and revoked grant rows remain history; hiding a record from live reads is not deletion. Rejoining an organization or reconnecting a provider does not restore a revoked member grant or clear a retained suspension policy. ### .fair, settlement and units A `.fair` manifest describes attribution and economic distribution. Creative credit and payment shares are not the same field. Use the shared builder, validator and signing helpers instead of assembling a fee chain by hand. A manifest is not proof that money moved; a payment receipt and the ledger's recorded settlement outcome carry that meaning. Settlement behavior depends on its entry point and funding path. The canonical builder includes protocol, platform, node and buyer components; optional scope, tax and processor handling can affect a flow. There is no universal two-percent fee promise. Signature verification also differs between funded settlement and other paths, so do not claim that every unsigned manifest is rejected. Consult the pay contract and shared settlement implementation for the chosen flow. MJN is receipt-backed and withdrawable subject to the applicable receipt currency, funding and withdrawal rules. MJNx is emitted for in-platform use and is not withdrawable. Balances are separate per DID and unit. Settlement checks the target's accepted units and rejects unsupported units instead of silently converting MJNx to MJN. Neither a fixed fiat peg nor a future token launch is an integration guarantee. ### Agents, delegation and approval An agent has its own DID, signing key and credentials. Personal agent setup and organization provisioning are distinct flows. Organization provisioning and orphan adoption require the documented live human administrator checks and proof; an identity selector or a copied personal credential cannot substitute for them. Operator approval authorizes a particular operation or ceiling; it does not replace a user's consent, an app's requested scope or an agent's live grant. Long-running work must tolerate grants expiring or being revoked. Re-read authority at the documented boundary and display a refusal rather than falling back to shared credentials. The operator interface records signed loop events, decisions and command outcomes. A transport acknowledgement means delivery was attempted, not that work completed or a lease was acquired. Private briefs and artifacts retain their own access controls. Consult the Jin spec and loop contracts instead of interpreting local harness references as public capabilities. ### Connectors and custody People connect provider accounts on their Imajin profiles. Apps witness connected state and invoke authorized kernel operations; they do not implement their own copy of credential lifecycle or receive raw provider keys. App registration, organization membership, operator approval and member consent each answer a different authorization question. The vault supports node-sealed entries and delegation-grant entries. Tier 0 remains node-controlled, not zero-custody. Optional external-owner custody does not establish a universal deployment posture. Seal secrets through the documented credential controls, never chat, source, logs, issue text or copied environment examples. Organization-held provider keys are write-only, including for the loading admin. Live human owner/admin authorization with connections-service access controls lifecycle and member grants. Metadata reads expose status and provenance, not the credential or a generic export path. A human member requires an active per-member grant to use an org-held key. An assigned agent uses its verified principal relationship; live assignment, allowed services and revocation still apply per call. Member-held Postman access is a separate personal lifecycle. The kernel injects the credential only to the fixed official target and exposes reviewed saved-data reads, not arbitrary writes or live-request execution. App callers require the documented scope and current member consent; app-service callers also need operator approval. Organization tagging is attribution and standing, not transfer of secret ownership. Administrative suspension is checked before custody access. For app-hosted upstreams, the app declares exact destinations and method/path permissions on its registration. The member connects to that declaration and approves the permissions. Connection status returns a plain-text review list; a disconnected status is not evidence of prior consent. Changing the permission set requires reconnecting, while reordering it does not. Invocation is kernel-mediated. Read and write authority are separate; writes also require a documented reason. The destination is bound to member consent, credential injection stays in the kernel, redirects are refused and credential echoes are not returned. Successful calls and authorized upstream failures have signed member/app/org outcome metadata; authorization or admission refusals write nothing permanent. No database transaction spans upstream network I/O. The connections spec supplies limits, validation and error details. ### Communication and security limits Chat uses TLS in transit and stores plaintext at rest on the hosting node in `chat.messages_v2.content`. Push notifications carry the first 200 characters of the message preview. Message encryption is planned but not implemented; no forward-secrecy or post-compromise guarantee is made. Published public key bundles do not provide current message encryption. The kernel's WebSocket transport shares its HTTP server. Transport protection does not make stored message content secret from the hosting node. Integrations must account for notification previews and the service's current access controls rather than promising stronger confidentiality. ## How to integrate ### Connect an agent Give the agent its own DID and signing key through the existing [auth contract](https://jin.imajin.ai/auth/api/spec). The agent authenticates as itself. A person grants the required scoped delegation, bounded by capability, audience and expiry; revocation withdraws that authority. Keep the agent signer separate from the principal it serves. A relationship or selected DID alone is not permission to use the principal's connectors. The kernel's Streamable HTTP [MCP server](https://mcp.imajin.ai/mcp) is served at `/mcp`. Follow its protected-resource and authorization-server discovery, then the authorization-code flow with PKCE and explicit human consent. An agent-bound authorization records the agent and selected assigned principal separately. The token's subject remains the agent; each agent needs its own client registration and protected credential/refresh store, even on a shared runtime. Consent scopes are a ceiling, not a grant of all MCP tools. Surface and per-tool checks apply, and connector operations recheck their live authority. A request header cannot change a consent-bound assignment; a different principal or wider scope needs fresh consent. For contact with one person, the node serves `/reach//mcp` and that person's `/reach//openapi.json`. This is a reach-only surface, not the full kernel MCP catalogue. Public discovery does not authorize messaging: gated `reach_send` and requester-private `reach_status` calls require authority bound to that recipient. A reach bearer is not a general kernel API token, and receiving permission to contact a person never means acting as that person. The [OpenClaw plugin](https://github.com/ima-jin/openclaw-imajin-plugin) is the working example of an agent runtime integrating with the kernel under its own identity and explicit authority. Use the [kernel MCP runbook](https://github.com/ima-jin/imajin-ai/blob/main/docs/ops/openclaw-mcp.md) for the consent walk and agent/principal isolation. Use MCP for equivalent tools and retain the plugin's direct identity, attestation and inbound-message listener paths where documented; not every plugin operation has become an MCP tool. ### Build and register an app Start from the [app template](https://github.com/ima-jin/imajin-app-template) and [registered-app contract](https://github.com/ima-jin/imajin-ai/blob/main/docs/REGISTRATION.md). Give the app a distinct identity and declared permissions. Keep runtime credentials server-side. Use published `@ima-jin/*` SDK packages for external apps; `@imajin/*` is the workspace import scope. A manifest's `private` flag is a publishing safety measure, not evidence that an SDK is unavailable. For app-owned signing keys, follow the SDK bootstrap and keystore contract. For declared app secrets, manifest sync creates declaration slots only. Generated credentials need a separate signed generation action; operator-supplied values need masked entry and a separate countersignature. Pending staging is not an active credential. Load approved vault credentials into typed server-only configuration before dynamically importing a database or server module that consumes them; do not copy values into `process.env`. ### Sign a person into the app Use the [auth-client SDK](https://github.com/ima-jin/imajin-ai/blob/main/packages/auth-client/README.md). Begin sign-in at the app's own login handler so it creates app-isolated state before redirecting to kernel consent. Keep the registered callback and full public app URL consistent, including a basePath where the app uses one. Forward root callback parameters before applying app login or claim gates. The callback verifies state and exchanges the short-lived, single-use authorization code using proof of possession of the app's signing key. Establish the session only from the kernel-returned subject and attestation. Client profile fields are display data, not identity authority. Configure the same stable app DID for session handlers and readers. The SDK derives an app-specific host-only cookie name; the kernel session cookie is reserved. Signing out of one app must not clear the kernel's session or another app's cookie. Read the SDK contract for explicit cookie overrides and redirect handling. ### Call a service Fetch the owning service's live spec before implementing a request. Use the documented token type and scopes rather than inferring them from a URL. User-delegated app tokens carry consented user authority. App-service tokens authenticate machine operations with current operator-approved service scopes; they do not impersonate a human session. For business-context operations, preserve the selected acting identity and handle a denied role or service selection explicitly. An arbitrary DID in a request body is a selector, never authority. Where an operation requires a human session, an agent or app token is not a substitute. Do not use internal keys, development previews or cron handlers as public integration shortcuts. Specs enumerate contracts; the implementation and security disclosures explain deployment qualifications. Handle refusals, expiry, revocation and rate limits as normal control flow without retrying under another identity. ### Add agent or model access Authenticate as the calling agent and obtain only the principal grants needed for the task. For inference, discover the caller's usable models and routing diagnostics rather than hard-coding a provider lane or assuming every loaded key is usable. The agent remains the signer even when a verified principal supplies the credential. Human member grants and assigned-agent relationships remain distinct. Agent self-discovery through `GET /infer/v1/self` returns the authenticated agent's identity, held inference routes, authority, grant status, usable models and fixing controls. Its read-only MCP/HTTP rows reuse the tool-call authorization predicates and report the authority lane and `authorizedScopes` without probing credentials. Inference scope does not grant tool authority. The `?agents=1` operator view supplies the bound-serving-agent cards on `/jin` through the same projection and live inference resolver. It requires a direct principal session, with org owner/admin authority for org act-as, refuses agent delegation and does not disclose agents' private connectors or other clients. Provider-billed reconciliation uses separately sealed billing credentials and explicit billing scope. It is not the same as incurred usage metering. A missing cost is not evidence that usage is free, and kernel-observed usage is not a complete provider invoice. ### Run a node or an internal service Use the [contributor setup](https://github.com/ima-jin/imajin-ai/blob/main/docs/DEVELOPER.md), [environment guide](https://github.com/ima-jin/imajin-ai/blob/main/docs/ENVIRONMENTS.md) and [deployment runbook](https://github.com/ima-jin/imajin-ai/blob/main/deploy/README.md). The kernel has no basePath; independently deployed apps own their routing prefixes and deployment procedures. Source support alone does not prove a host is configured or a rollout is complete. Corpus is a separate internal daemon reached through its configured service URL. GitHub partitions use the registry-resolved source-owner group DID and explicit owner-issued grants; workspace sources remain principal-owned. Membership, a registry stub or a local GitHub CLI login is not source-owner consent. See the [corpus-owned runbook](https://github.com/ima-jin/imajin-ai/blob/main/apps/corpus/README.md) for connector selection, its private `/spec`, and operational procedures. ## Service specifications Each link corresponds to a service spec definition in the kernel source. Substitute the integrating node's origin as appropriate. These contracts are the route catalogue; they are not a deployment inventory, a release history or a permission grant. - [Auth API](https://jin.imajin.ai/auth/api/spec): Authentication, schemas and operation contracts. - [Calendar API](https://jin.imajin.ai/calendar/api/spec): Authentication, schemas and operation contracts. - [Chat API](https://jin.imajin.ai/chat/api/spec): Authentication, schemas and operation contracts. - [Cloudflare API](https://jin.imajin.ai/cloudflare/api/spec): Authentication, schemas and operation contracts. - [Connections API](https://jin.imajin.ai/connections/api/spec): Authentication, schemas and operation contracts. - [Github API](https://jin.imajin.ai/github/api/spec): Authentication, schemas and operation contracts. - [Google API](https://jin.imajin.ai/google/api/spec): Not publicly served at this origin; consult the [spec source](https://github.com/ima-jin/imajin-ai/blob/main/apps/kernel/api-spec/google.yaml). - [Infer API](https://jin.imajin.ai/infer/api/spec): Authentication, schemas and operation contracts. - [Jin API](https://jin.imajin.ai/jin/api/spec): Authentication, schemas and operation contracts. - [Media API](https://jin.imajin.ai/media/api/spec): Authentication, schemas and operation contracts. - [Notify API](https://jin.imajin.ai/notify/api/spec): Authentication, schemas and operation contracts. - [Pay API](https://jin.imajin.ai/pay/api/spec): Authentication, schemas and operation contracts. - [Profile API](https://jin.imajin.ai/profile/api/spec): Authentication, schemas and operation contracts. - [Quickbooks API](https://jin.imajin.ai/quickbooks/api/spec): Authentication, schemas and operation contracts. - [Registry API](https://jin.imajin.ai/registry/api/spec): Authentication, schemas and operation contracts. - [Usage API](https://jin.imajin.ai/usage/api/spec): Authentication, schemas and operation contracts. - [Vault API](https://jin.imajin.ai/vault/api/spec): Authentication, schemas and operation contracts. ## Further reading - [Concise agent entry point](https://imajin.ai/llms.txt): Platform shape and integration starting points. - [Developer guide](https://imajin.ai/developer-guide): Consumer-facing concepts and integration guidance. - [Whitepaper](https://imajin.ai/whitepaper): Primitive grammar and economic model. - [How it works](https://imajin.ai/how-it-works): The three pillars and how an agent runtime, the Imajin plugin and the kernel fit together. - [Compare](https://imajin.ai/compare): Where Imajin sits next to identity providers, agent frameworks, hosted assistants and web3 agent projects. - [Why we built it this way](https://imajin.ai/project): The reasoning behind the design, the current state and its honest limits. - [Join the alpha](https://imajin.ai/alpha): Apply as a tester, integrator or partner, or book a demo. - [Canonical patterns](https://github.com/ima-jin/imajin-ai/blob/main/docs/guide/canonical-patterns.md): Shared implementation boundaries. - [Security disclosures](https://github.com/ima-jin/imajin-ai/blob/main/SECURITY.md): Trust assumptions and implementation limits. - [Repository](https://github.com/ima-jin/imajin-ai): Source, app/package READMEs and operator documentation.