saltbo Integrate A Realmroot Resource Server
Integrate an existing protected API with Realmroot without redesigning its business resource model. Treat Realmroot registration as the final publication step, not as a substitute for a conforming Resource Server.
Step 1: Establish Existing Inputs
Read the repository instructions, deployed API contract, authorization model, scope vocabulary, environments, and tests. Identify:
- the stable protected resource URL;
- the existing OpenAPI 3.x document;
- the provider-owned Resources Realmroot will expose;
- the existing requestable scopes and protected operations;
- whether the provider or Realmroot owns authorization.
Do not invent domain Resources, routes, methods, representations, or business scopes. If any required input is absent or internally inconsistent, report it as an API-design prerequisite and stop that part of the integration.
This step is complete when the integration can refer to existing canonical API and authorization decisions.
Step 2: Select The Authorization Mode
Read references/integration-requirements.md completely, then choose one mode:
- use native when the API trusts Realmroot as its authorization server;
- use external when the provider owns its users, authorization server, tokens, and consent;
- add brokered account connection only when a native Resource Server must retain another provider's credentials behind its own boundary.
Deployment outside Realmroot does not make a Resource Server external.
Step 3: Assess Conformance
Evaluate every requirement applicable to the selected mode. Report results by capability ID and classification:
- REQUIRED: block registration or enablement until it passes;
- CONDITIONAL: block only when the integration selected the condition;
- RECOMMENDED: report the operational or product limitation when absent, but do not present it as a protocol failure.
Use live metadata, OpenAPI, implementation, and tests as evidence. Do not infer conformance from prose or planned work.
Step 4: Implement Missing Integration Capabilities
Implement only the missing Realmroot integration surface identified by the assessment: discovery metadata, OpenAPI advertisement and security mapping, authorization-server interoperability, token and DPoP validation, actor preservation, account connection, revocation, or lifecycle signals.
Keep the business API's existing resources and semantics intact. Update the metadata, OpenAPI security declarations, enforcement, and tests together when the integration changes scope exposure or authorization behavior.
This step is complete when every applicable REQUIRED and CONDITIONAL capability has direct implementation and test evidence.
Step 5: Register Through Realmroot
Read references/registration.md. Use
$realmroot for Agent identity, management authority, Connector or Resource
Server mutations, controller account connection, and access requests. Require
that Skill to be installed; do not reproduce its enrollment or credential
procedures.
Register the exact protected resource URL only after its unauthenticated discovery surface is reachable. Use no Connector for native mode. For external mode, configure the Connector required by the live Realmroot contract and let the controller connect the account. Never copy provider tokens into Realmroot or Restish manually.
Read the created representation back and confirm ownership, mode, availability, connection state, and discovered scope registry.
Step 6: Prove End-To-End Access
Run the repository's narrowest conformance and integration checks, then use
$realmroot as a real Agent to:
- discover the registered Resource Server;
- discover and select a provider-owned Resource;
- request the exact scopes required by one existing operation;
- connect the target OpenAPI contract through Restish;
- invoke one real read operation;
- invoke and read back one safe write when the existing API exposes one.
Report the final capability matrix, remaining RECOMMENDED gaps, automated checks, and real operation evidence. The integration is complete only when all applicable REQUIRED and CONDITIONAL capabilities pass and direct target API traffic succeeds with the expected identity, audience, scope, actor, DPoP binding, and local authorization result.