Building a Repository Connector

A connector exposes one records repository to AccessPoint so that coordinators can browse, search, capture and collect its records inside every Documents workspace (request, assignment, task, assessment, incident, complaint). Each captured document records its provenance: source path, version and SHA-256.

This guide is for the developer building a connector for a records system AccessPoint does not ship one for (or extending a shipped one), and for the engineer who hosts, registers and supports it. You can build on the .NET SDK or in any language against the OpenAPI specification. It is not a copy of the wire specification: the OpenAPI document is the authoritative contract for every field.

Where to get things

Every release publishes the connector framework beside the app packages, in a connectors/ folder:

• https://get.realizer.io/public/accesspoint/latest/connectors/ is the promoted release.
• https://get.realizer.io/public/accesspoint/{version}/connectors/ pins a version.
• https://get.realizer.io/public/accesspoint/dev/connectors/ is the newest build, for evaluation only.

The connector version is the API version, so an API upgrade is the cue to redeploy connectors from the same path. Connectors are covered by the flat-rate license; there is no per-connector fee.

What a connector is, and is not

Three facts shape everything below.

• The AccessPoint API is the only client. The browser never calls a connector. Every browse, search and capture runs from the browser to the API to the connector. The API pulls the bytes server-side, streams them into the case's blob storage, verifies the hash and runs the same post-upload pipeline an uploaded file gets. A connector needs no CORS, no user-facing UI and no inbound reach to AccessPoint, because the API always dials it.
• A connector is read-only. The protocol has no write-back. A capture is always a frozen snapshot copy into AccessPoint storage, never a live reference.
• Two kinds, one interface. The built-in kinds (Azure Blob container, MCP search/fetch server, SQL view, CMIS 1.1 repository) run inside the API and are configured, not coded. Customer code never runs inside the API process. If a built-in kind covers your source, configure it in Settings > Foundations > Repository connectors. Everything else is a Remote connector, a separate HTTPS service that speaks the protocol, which is what this guide is about.

On every call the connector receives the tenant, a correlation id, the attributed user, the case reference and the purpose. That is enough for the source system's own logs to record who looked at what, for which case and why. Use it.

Prerequisites

The protocol at a glance

The protocol is stateless JSON over HTTPS: camelCase, enums as strings, nulls omitted. Every request carries Authorization: Bearer <token> and the X-AP-* attribution headers. A connector must authenticate the caller before it reads any attribution header, because the headers are trusted only when the token proves the caller is the AccessPoint API.

Endpoints

Routes are relative to the connector's registered base URL.

Headers

On every request from the API:

System calls (the health sweep and Test connection) carry no user and no case. On every response the SDK sets Cache-Control: no-store, X-AP-Protocol-Version: 1 and the echoed X-AP-Request-Id. A content response may add X-AP-Sha256: sha256:<hex> when the connector knows the full-content digest before streaming.

Wire models

Capability flags

Absent or false means the API never calls the corresponding route.

metadataSchema declares the keys an item's metadata may carry: key, type (string, number, boolean, date, dateTime, string[]), per-locale labels and facetable. It drives the picker's details flyout and facets. Declare only what you implement.

Paging cursors

Every listing takes an opaque cursor and a pageSize (1 to 200, default 50; the API clamps it to the manifest's maxPageSize) and returns nextCursor to be handed back unchanged. Never use an offset. The easiest robust cursor is the id of the last item returned, in a stable sort order, so paging survives restarts and load balancing.

Collection jobs depend on this. The API persists its walk position between flushes and re-lists a page after a restart, skipping items it already has. A cursor that drifts would double-capture or skip records. The conformance test lists page two when a cursor came back and fails a connector whose second page repeats an id from the first.

Search modes and filters

The API composes a neutral query (free text, a date window with from and to, an optional container scope, and connector-declared filters) or passes a native query through verbatim.

containerId restricts results to that container and its descendants. Results are an item page like any listing.

Health and the conformance sequence

GET health is probed every five minutes by the API's health sweep. The result maps to the status administrators see: 401 or 403 is Unauthorized, a protocol refusal is Incompatible, a transport failure, timeout, 5xx or down is Unreachable, and degraded is Degraded. Health is advisory: the tile is greyed with a tooltip but stays clickable. Answer honestly and quickly, and put the reason in detail. Never put a secret there, because administrators see the text.

Test connection in Settings runs the same sequence as the SDK's self-test, each step reported as Pass, Fail or Skip with detail and duration:

1. manifest: fetched and well-formed (id, names.en, protocolVersions, limits, a valid icon). A Fail stops the run.
2. protocolVersion: protocolVersions contains 1, and a request sent with version 999 is refused 400 unsupported_protocol_version. Built-ins skip the wire half.
3. identityMode: a valid mode. Delegated fails; ApplicationWithUserCheck without checkAccess fails.
4. roots: every root validates. Zero roots passes ("nothing to browse for this caller").
5. children: the first root's children (page size 10). Page two is fetched when a cursor came back and must not repeat an id. The SDK self-test also checks that pageSize=201 is refused (a warning otherwise).
6. search: when declared, a short query in freeText, else structured. Skipped when only native is declared.
7. item: a fetchable item resolves to the same id. An unknown id must answer 404 not_found (a warning otherwise).
8. content: the first 64 KB through a Range request. The SDK self-test warns when Accept-Ranges: bytes is missing or the range was ignored. The hash is verified only when the whole item fit, and a mismatch fails the step.
9. checkAccess: when declared, the answer may only contain ids that were asked about.
10. health: status is ok, degraded or down.

Error shapes and codes

Every non-2xx response is application/problem+json with type (urn:accesspoint:connector-problem:<code>), title, status, detail, instance, code, requestId and retryAfterSeconds. The API dispatches on code first and the HTTP status second, and relays the code to the client unchanged.

On its own side the API adds connector_unavailable (502, a transport failure or an open circuit), connector_disabled (409), connector_not_visible (403), connectors_disabled (403) and invalid_anchor (400). These never reach a connector.

What the API does around your connector

Design for these facts.

• Timeouts per call: browse, search and manifest 30 seconds; content 10 minutes per item; health 10 seconds. JSON responses are capped at 4 MB.
• Circuit breaker: five consecutive transport failures (timeouts, connection errors, 5xx) open the circuit for 60 seconds. Every call then fails fast with connector_unavailable and the tile greys. A 4xx problem is an answer and never counts. Test connection, edit and delete reset it.
• Retries: idempotent GETs may be retried. The two POST routes (search and checkAccess) are never retried. Keep every GET idempotent and free of side effects.
• Manifest caching: list views use the stored manifest whatever its age. It is refetched when older than an hour, falling back to the stored copy when the connector is down. Registration, Test connection and Refresh manifest force a fetch.
• Outbound allow-list: the API only calls URLs under a registered base URL (scheme, host and port exact, path prefix) and never follows redirects. A connector cannot bounce the API elsewhere, and a webUrl is never fetched by the API; it is handed to the user's browser.
• Rate limit: treat 60 requests per minute per user as the ceiling your source must tolerate from one coordinator.
• Capture path: GET items/{id} to resolve and de-duplicate, then, in user-check mode, POST checkAccess, then GET items/{id}/content streamed into blob storage with SHA-256 computed on the way, then GET items/{id} again to record provenance. That second call is why a connector that only learns the hash while streaming should surface it on the next item read.

Building a connector with the SDK

Reference the packages

<PackageReference Include="Realizer.AccessPoint.Connector.Sdk" Version="x.y.z" />

x.y.z is the AccessPoint API version the packages were stamped with. The SDK brings the protocol models, the request dispatcher, Entra bearer validation, the hosting helpers, the conformance self-test and the MCP facade. It uses the ASP.NET Core shared framework.

Implement IRepositorySource

IRepositorySource is the one interface a connector author implements; the dispatcher maps every protocol route onto it. Every method receives a call context with the protocol version, tenant, request id, user id, user UPN, user groups, case reference, purpose, accept-language (with a PreferredLocale() helper), the authenticated caller principal and whether a user is attributed.

pageSize arrives already validated and defaulted. Rules that make a source behave well inside AccessPoint:

• Return null for an unknown id from GetItemAsync and OpenContentAsync, which becomes 404 not_found. Throw ConnectorException for anything the caller must distinguish: AccessDenied(), TooLarge(), SourceUnavailable(detail, inner, retryAfterSeconds), RateLimited(seconds), InvalidQuery(), NotFound() and Unsupported(). Common .NET exceptions are mapped for you.
• Ids are opaque and stable. A captured document keeps the id as provenance for the life of the case. Never change what an id means.
• Order stably and page by cursor.
• Attribute everything. Log the request id, user UPN, case reference and purpose at Information level so the source's administrators can answer "who looked at this and why". In user-check mode, trim by the attributed user and fail closed: no attributed user, an unresolvable principal or an unreadable ACL means the item is excluded, not included.
• Localize from the manifest. names, descriptions and metadataSchema[].labels are per-locale dictionaries. en is required and is the fallback.
• Register the source as a singleton or scoped service. The dispatcher resolves it per request.

The manifest

new ConnectorManifest
{
    Id = "contoso.records",                              // reverse-DNS, never changed once documents exist
    Names = { ["en"] = "Records system", ["fr"] = "Système de gestion des documents" },
    Version = "1.0.0",
    ProtocolVersions = [1],
    Icon = "Database",                                    // Fluent UI icon name, or a PNG data URI of 16 KB or less
    IdentityMode = IdentityModes.Application,             // or ApplicationWithUserCheck (+ CheckAccess = true, WantsGroups as needed)
    Capabilities = new ConnectorCapabilities
    {
        Browse = true, Fetch = true,
        Descendants = true,                               // only if GetDescendantsAsync is real
        Search = new SearchCapability { Modes = [SearchModes.FreeText, SearchModes.Structured], Filters = ["date", "type"] },
        CheckAccess = false,
    },
    MetadataSchema = [ new MetadataField { Key = "type", Type = "string", Facetable = true, Labels = { ["en"] = "Record type" } } ],
    Limits = new ConnectorLimits { MaxPageSize = 200, MaxContentBytes = 2L * 1024 * 1024 * 1024 },
}

Keep the manifest cheap and deterministic: the API caches it for an hour and Test connection fetches it first. A connector may derive capabilities from its source, but the manifest must not depend on who is asking.

Content streaming

OpenContentAsync returns a content result with the stream, the Length of the full content when known (needed for Content-Length and suffix ranges), ContentType (application/octet-stream when unknown; the API sniffs the bytes regardless), ETag, LastModified, FileName (emitted as an inline Content-Disposition), Sha256 (emitted as X-AP-Sha256 when known up front) and AppliedRange.

• Stream; never buffer. The dispatcher copies the stream to the response in 80 KB blocks and disposes the result afterwards.
• Ranges are handled for you. Return the full stream and ignore the range argument. The dispatcher serves bytes=start-end, bytes=start- and bytes=-suffix itself, seeking when the stream allows and reading past the offset otherwise, and answers 416 for an unsatisfiable range. Set AppliedRange only when the source already served the partial bytes.
• Hashes are optional but valuable. hash on the item and X-AP-Sha256 on the content let the API verify the captured bytes. A mismatch is flagged on the document, never blocking, and Test connection fails the content step when the whole item was read. If hashing on listing is too expensive, compute the digest while a full fetch streams and surface it on the next GET items/{id}. The file share, OnBase and OpenText connectors all do this with a small in-memory hash cache.
• Size caps. Answer 413 too_large above your maxContentBytes, and list the item anyway so the user learns why it was skipped.

Errors

ConnectorException carries a Code, a Status (the code's default unless overridden), a Detail shown to administrators and an optional RetryAfterSeconds. The dispatcher also maps common .NET exceptions:

A failure after the response has started aborts the connection rather than appending JSON to a half-written body. Never put secrets, internal paths or stack traces in Detail.

The dispatcher

The request dispatcher is the host-agnostic router. For every request it sets the response headers, authenticates before reading anything else, enforces X-AP-Protocol-Version, parses the route, builds the call context, resolves your IRepositorySource, dispatches, and writes any failure as problem+json. It reads JSON bodies up to 1 MB by default, refuses non-JSON bodies, validates pageSize, parses modifiedFrom and modifiedTo as ISO 8601, serves HEAD for content, and validates emitted items. Item validation is log-only, so a connector under development can see what it gets wrong without being refused.

Dispatcher options come from the Connector configuration section: TrustHostAuthentication (default false; with no SDK authentication registered every request is refused 401, so the dispatcher fails closed), SupportedProtocolVersions (default [1]), MaxPageSize (up to 200), DefaultPageSize (50), MaxRequestBodyBytes, ValidateItems and AllowHead.

Minimal-API hosts map it with one call:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAccessPointConnector(builder.Configuration);   // "Connector" section: auth + dispatcher options
builder.Services.AddRepositorySource<MySource>();
builder.Services.AddAccessPointMcpFacade();                        // optional
var app = builder.Build();
app.MapAccessPointConnector();                                     // or MapAccessPointConnector("connector") under a prefix
app.MapAccessPointMcpFacade("/mcp");                               // optional
app.Run();

MapAccessPointConnector maps one catch-all endpoint (GET, HEAD, POST), marked anonymous for the host's authorization middleware because the dispatcher authenticates itself. An Azure Functions host does the same with one catch-all HTTP trigger that forwards the request context to the dispatcher.

Entra authentication

The API authenticates with an Entra access token from the customer tenant, issued to the API's managed identity, for the connector's audience. The SDK validates three things and refuses to start if any is unconfigured:

1. Issuer. The customer tenant, in both the v2 (https://login.microsoftonline.com/{tid}/v2.0) and v1 (https://sts.windows.net/{tid}/) forms. Signing keys come from the tenant's OpenID Connect metadata.
2. Audience. Connector:Audience plus Connector:AdditionalAudiences. List both the App ID URI and the app registration's client id: a v1 access token carries the App ID URI as aud, a v2 token carries the client id, and which one Entra issues depends on the registration's accessTokenAcceptedVersion.
3. Caller. The token's oid must be in Connector:AllowedCallerObjectIds (the AccessPoint API's managed identity), or its azp or appid in Connector:AllowedCallerAppIds (an app registration used for local testing). An empty allow-list refuses to start, because otherwise any principal in the tenant could call you.

"Connector": {
  "TenantId": "<customer tenant id>",
  "Audience": "api://accesspoint-connectors.contoso.onmicrosoft.com",
  "AdditionalAudiences": [ "<client id of that app registration>" ],
  "AllowedCallerObjectIds": [ "<object id of the AccessPoint API's managed identity>" ],
  "AllowedCallerAppIds": [],
  "InstanceBaseUrl": "https://login.microsoftonline.com",
  "Authentication": "Sdk"
}

Each list accepts a JSON array or a comma-separated string, so the same keys work as App Service application settings (Connector__AllowedCallerObjectIds). For sovereign clouds set InstanceBaseUrl. MetadataAddress, RequireHttpsMetadata and ClockSkew (2 minutes) are also available.

App Service Authentication instead. On App Service or Functions you may let the platform validate. Enable Authentication with the Microsoft provider, set the allowed token audiences to your audience, restrict allowed client applications to the API's managed identity, and set Connector:Authentication to Host. The SDK then validates nothing itself. Never set Host without such a gate, because the dispatcher would accept anonymous calls.

Self-test and the command-line tool

ConnectorSelfTest runs the ten conformance steps against any base URL and returns a report (Steps, Manifest, Passed, ToText()). It never throws for connector failures; they become Fail steps. Its options let you stamp a tenant, a user id, UPN and groups (needed to exercise a user-check connector), a case reference, the head size (64 KB) and how far below the roots to look for a fetchable item. Pass an in-process test-server client to run it without a network.

The same sequence ships as the accesspoint-connector command-line tool (AccessPoint.Connector.Tools.zip):

accesspoint-connector selftest <baseUrl> [--token <bearer>] [--tenant <tid>] [--user-id <oid>] [--user-upn <upn>] [--groups a,b] [--json]
accesspoint-connector manifest <baseUrl> [--token <bearer>]
accesspoint-connector token --tenant <tid> --client-id <appId> --client-secret <secret> --scope <audience>/.default

Exit code 0 means pass, 1 means fail, 2 means a usage error. token mints a client-credentials bearer for local testing. Register that app's client id in Connector:AllowedCallerAppIds (or its service principal's object id in AllowedCallerObjectIds) so the connector accepts it. The zip runs as dotnet AccessPoint.Connector.Tools.dll ....

The MCP facade

AddAccessPointMcpFacade() and MapAccessPointMcpFacade("/mcp") publish the same IRepositorySource as an MCP server with exactly two read-only tools: search (free text returns { results: [{ id, title, url }] }) and fetch (an id returns { id, title, text, url, metadata }). This is the convention Microsoft 365 Copilot federated connectors and other AI-client connectors share, served over Streamable HTTP in stateless mode.

search picks freeText, else structured, else native from your manifest. fetch returns the content as text for text, JSON, XML and YAML records (up to 1 MB by default) and the record's metadata rendered as text for anything else. There is no PDF text extraction; capture the record through AccessPoint for that. The facade requires an authenticated caller on the connector's own bearer scheme by default; turn that off only behind a gateway that authenticates for you. Facade calls arrive without protocol headers, so the call context is built from the caller's oid and preferred_username claims.

Publishing the facade is optional and independent of AccessPoint. Conversely, AccessPoint's MCP built-in consumes any search/fetch server as a search-only source (captures become HTML records), so an MCP server you already have can be registered without writing a connector.

Unit tests

Host the dispatcher in an in-process test server over an in-memory repository source, with injected token-validation parameters, so your tests run without a network or an Entra tenant. Run the self-test against that same host to prove conformance in your build pipeline.

Templates

Two templates ship with the SDK sources. Copy the folder, rename the project and the namespace, replace the template repository source, and keep the shape: one IRepositorySource, one Program.cs. Both run and pass the self-test out of the box against a tiny in-memory tree, which is the fastest way to see the protocol working end to end before you touch a real source.

Steps that apply to either:

1. Fill the Connector section: tenant id, audience, the app's client id and the API's managed-identity object id.
2. Implement the source.
3. Run it (dotnet run or func start) and run accesspoint-connector selftest https://localhost:<port>/ --token <bearer> with a token from accesspoint-connector token ....
4. Deploy with HTTPS and a managed identity for the source.
5. Register the URL in Settings > Foundations > Repository connectors > Add connector > Remote and run Test connection.

For an on-premises Windows service there is no template. The network file share connector is the reference: it runs the same binary as a console app or a Windows service, and each connector ships a Dockerfile for a Linux container where the identity mode allows it.

The shipped connectors as worked examples

The five publisher connectors are complete, tested implementations. Read the one closest to your source before writing your own. Each zip has a guide beside it under docs/ in the release folder. Every one accepts the same four Connector:* authentication keys, exposes the Mcp:Enabled facade switch, caps content at 2 GB by default (Axon Evidence: 50 GB) and computes the SHA-256 while a full fetch streams, surfacing it on the next item read.

Network file share: the reference connector

It shows a hierarchical source with a natural folder tree, Application with user check against a real ACL model, and the on-premises hosting story.

• Ids are a base64url encoding of the root id and relative path: opaque, URL-safe, free of /, and stable as long as a root id is never renamed after documents have been captured.
• Ordering and cursors: siblings by name (case-insensitive), a subtree depth-first. Every cursor is the id of the last item returned.
• User check: it resolves the attributed UPN to an Active Directory SID and token groups, adds the well-known Everyone and Authenticated Users SIDs, evaluates the NTFS ACL with Deny always winning, caches the principal for five minutes, and fails closed on a non-Windows host. That is why the Dockerfile supports Application mode only.
• Hashing: hashing on listing is off by default because it is expensive on a large share. The hash is computed while a full fetch streams and reported on the next item read.
• Search: structured (name contains, plus extension, name and date filters) and freeText (every term must appear in the file name). There is no content index, and the guide says so rather than pretending.
• webUrl: none by default. AccessPoint keeps a source link only when it is an absolute http or https address, so a file:// URL would be dropped. A connector for a web-based source should return an https webUrl.
• Hosting: a domain-joined Windows host with SMB reach beside the Hybrid Connection Manager (Hybrid Connections tunnel TCP, not drive mounts), with Kestrel bound to a certificate whose SAN is the registered hostname.

Hyland OnBase

It shows a source with no folder tree and a vendor REST API behind an OAuth client: how to synthesize browse, map a keyword model to the neutral query, and be explicit about what is unverified.

• Browse is synthesized. Roots are Document Type Groups (when the API server exposes them) or Document Types. A type lists its documents newest first, paged inside a bounded query. path is group, type and name; keyword values ride in metadata and the manifest declares them from a cached keyword-type catalogue.
• Search: structured (document type, keyword equals or contains, document-date range), freeText (keyword mapping, or the Full-Text module when enabled) and native (a validated query body passed through).
• Identity mode: Application. The connector runs as one OnBase service user. What that user's groups can see is what coordinators see, and every call logs the attributed user, case and purpose. checkAccess is not declared, so Test connection skips it.
• Versions only when revisions are enabled in the connector's configuration.
• Honesty about vendor facts: the connector's guide lists the API-server behaviors to verify against the customer's installation (grant types, endpoint paths, full-text availability). Do the same for your vendor.

OpenText Content Server and GCdocs

It shows true impersonation, where the source itself trims by user, plus a native query language and a multi-mode authenticator.

• Impersonation modes: token exchange (OTDS OAuth, recommended for GCdocs) or ticket-for-user make the manifest declare ApplicationWithUserCheck and run every call (browse, search, versions, content) as the attributed user, so Content Server's own permissions do the trimming. A mode of none declares Application with one service identity. A call without user attribution under an impersonating mode is refused or returns nothing, which is failing closed. A setting chooses whether the UPN or the user id is the Content Server login.
• checkAccess runs under the user's credential, falling back to a per-node read where the batch endpoint is absent. Credentials are cached ten minutes per principal and re-acquired once on a 401.
• Ids are node ids (the root defaults to the Enterprise Workspace). They are numeric, so provenance survives renames and the %2F problem described under Ids never arises.
• Paths come from the node's ancestors, trimmed at the first configured root.
• Search: structured (name words, type, date range, container), freeText (full text) and native (your own where clause, validated, with the container scope appended).
• Ranges are forwarded to Content Server once as a probe. If it answers 200, the connector stops forwarding and the SDK serves ranges by reading past the offset. Content is always the current version.

Laserfiche

It shows a cloud vendor API behind a signed client-credentials assertion, a native folder tree with OData paging, a search-task lifecycle whose results expire, an export-then-download content path, and how to stay under a per-account rate limit.

• Two deployments, one source: Laserfiche Cloud (a service principal; the token request carries a JWT signed with the access key) or the self-hosted API server (password grant). Every route is a configuration key because the self-hosted prefix is unverified.
• Ids are a base64url encoding of repository id and entry id. Numeric entry ids survive renames and moves, and the repository segment disambiguates multi-repository accounts. A shortcut is listed under its target's id so a document is captured once.
• Cursors carry the server's paging state: a folder cursor names the next link being consumed plus an offset inside it, so a name filter can span server pages. A search cursor names the search task and the skip. An expired search task is re-issued with the same command.
• Content is export-then-download: an export request returns a link the connector streams, sending the bearer only to the API's own host, probing Range once, and re-exporting once when the link has expired.
• A shared rate budget keeps every AccessPoint user together under the cloud service's per-account limit, answering 429 rate_limited with a retry-after rather than burning billed calls.
• Search composes the vendor's own syntax and refuses values containing quotes or braces instead of guessing escaping rules. descendants is declared only when recursive search is switched on, because that behavior is unverified.

Axon Evidence

It shows a flat, immutable evidence store behind an OAuth API client, large media objects, and a download path that leaves the vendor's host.

• Browse is synthesized from evidence facts: roots such as Cases, Categories, Recorded on (year, then month) and Owners, each a bounded search paged by the vendor's own cursor with a capped offset fallback. A single-file evidence item is its file; a multi-file one is a container. descendants expands evidence into files across protocol pages, while the roots refuse collection (501) because they would walk the whole agency.
• Ids are base64url encodings of the root, the evidence id, or the evidence and file ids, with no /.
• Content is streamed and never buffered under a 50 GB default cap, with at most one redirect to an allow-listed download host and the bearer never forwarded off the agency host. SHA-256 is computed while streaming, and the vendor's declared digest is mapped when present.
• Rate limits: a 429 with a short Retry-After is waited out once, a longer one surfaces as rate_limited, and a connector-side sliding window keeps one deployment inside the vendor's per-agency limit.
• Identity mode: Application only. An API client has no user context, so every call logs the attributed user, case and purpose; the vendor's own audit names the API client.
• Every unverified vendor fact (paths, query parameter names, cursor shape, token lifetime, redirect and range behavior) is a configuration key, and the connector's guide has a table to verify them against the customer's system. One pattern lesson worth carrying over: configuration binders append to a pre-populated list, so list options that ship with defaults should default empty and expose an effective view, or a configuration file that repeats the defaults doubles them.

Identity modes and how the user reaches the connector

The manifest's identityMode states how the connector treats the person behind a call. AccessPoint applies its own gates first (the feature toggle, the connector's visibility rule, exactly one case anchor, and the case-level rule identical to an upload) and only then honours the connector's mode. A user therefore never reaches a connector for a case they could not upload to.

In both supported modes the bearer token is the API's managed identity, and the user travels only as attribution headers. The API never forwards a user's token to a connector, and there is no delegated flow to configure on either side. A connector that must act as the user does its own principal mapping from the UPN or object id: the file share connector resolves the UPN to an AD SID, and the OpenText connector exchanges the UPN for a token or ticket under its own OAuth client. If your source cannot impersonate from a UPN, choose Application and let AccessPoint's case-level gate be the gate. Do not fake per-user trimming.

Two consequences to design for. A per-user view must never be cached across users, so key every cache by the attributed principal. And because system calls arrive with no user, a user-check connector should answer them sensibly: a health probe needs no user, and a roots listing with no user may legitimately be empty, which the conformance test treats as a pass.

Ids: the transport rule

An item id is opaque to AccessPoint: any content, up to 1024 characters, reinterpreted by nobody and stored verbatim on every captured document as provenance. Two rules govern how it travels.

API to connector: ids are percent-encoded in the path, exactly once. The SDK's dispatcher prefers the request's raw target over the server-decoded path and unescapes exactly once, so an id containing % or / round-trips on Kestrel. Where only the decoded path is available (an in-process test server, some proxies) it recovers the id by peeling a known tail (children, descendants, delta, content, versions) off the end and undoing %2F. If you implement the protocol without the SDK, decode once and be careful with %2F.

Browser to API: ids travel in the query string. The API's own proxy routes take container and item ids as query-string values, because the Azure App Service front end normalizes %2F in path segments back to real slashes before the request reaches the application. The same normalization can affect a connector sitting behind an App Service or Functions front end.

Therefore, prefer ids without /: base64url, numeric node ids or GUIDs. Encode whatever your source needs (drive and path, node id and version) into a URL-safe form, as the file share connector does. Never derive meaning from an id's shape on the way back in beyond decoding it.

Hosting, registering and testing against a dev tenant

Choose a host

Give an Azure-hosted connector its own managed identity for the source and keep source secrets as Key Vault references. A connector never needs inbound reach to AccessPoint or to the publisher.

On premises through Hybrid Connections. An App Service cannot see the customer's network, but a Hybrid Connection gives it a TCP path to one host and port inside it. The customer deploys (or redeploys in upgrade mode) with deployHybridConnections=true and one host:port entry per connector host, and installs the Hybrid Connection Manager on a machine that can reach the connector (outbound 443 to *.servicebus.windows.net only). The connector is registered as https://<that hostname>:<port>/ with Reached through a Hybrid Connection on. The hostname must be one the manager's machine resolves, never localhost, and the one your TLS certificate's SAN covers, because the API's own TLS session rides inside the tunnel. http:// is accepted only inside a Hybrid Connection, and AccessPoint warns about it. Only TCP is tunnelled, so a file share connector must itself have SMB access.

Configure authentication

In a split-tenant installation, Connector:TenantId is the Microsoft 365 tenant, and your connector's app registration must exist in that tenant. With no audience configured on either the registration or the tenant default, the API calls the connector without an Authorization header and the connector's 401 shows as health Unauthorized. That is the most common first-registration failure.

Run locally and self-test

1. Run the connector (dotnet run or func start).
2. Mint a bearer. Create an app registration in the dev tenant, list its client id in Connector:AllowedCallerAppIds, and run accesspoint-connector token --tenant ... --client-id ... --client-secret ... --scope <audience>/.default.
3. Run accesspoint-connector selftest https://localhost:<port>/ --token <bearer> --user-upn someone@dev.example. Pass a UPN the source knows when testing a user-check connector, or every step trims to nothing.
4. Read the report. Fail steps carry the problem code and detail. Warnings inside a Pass (a 200 for a ranged request, pageSize=201 accepted) are contract gaps worth fixing before they become a customer's Test connection question.

Deploy

Publish (dotnet publish -c Release) and zip-deploy to App Service or Functions, build the container image, or install the Windows service (sc.exe create ...). Configure the Connector section as application settings (Connector__TenantId and so on). Bind HTTPS with a certificate whose SAN is the hostname you will register. Verify with the CLI against the deployed URL before involving the administrator.

Register in AccessPoint and run Test connection

In the dev tenant, go to Settings > Foundations > Repository connectors > Add connector > Remote and enter the name, description, Base URL, Entra audience (empty means the tenant default), Reached through a Hybrid Connection, the visibility rule (a permission code, default document.manage, and/or roles) and Enabled. Saving fetches the manifest at once, and an unreachable manifest is refused with the connector's reason. Then press Test connection and read the ten steps. What a failure means:

Then use it. Open a request's Documents tab, choose your connector from the add-documents menu, browse, search, capture one record, and check Source details on the captured document (path, item id, version, hash Verified). Collect this folder on a container exercises descendants (or the level-by-level walk) and your cursors under load. The Azure Blob built-in is a useful reference fixture: if a capture from your connector misbehaves and one from a Blob connector on the same case does not, the difference is on your side.

Living with it

The health sweep probes every enabled connector every five minutes. Check health now and Refresh manifest run either on demand. The circuit breaker opens after five consecutive transport failures, and Test connection resets it. A connector that any document, open collection job or bound assignment repository references cannot be deleted, because provenance must keep resolving. It can only be disabled, which hides the tile and keeps the registration. See Connectors for the administrator's side.

Versioning and compatibility

• Protocol version. The API sends X-AP-Protocol-Version: 1 on every call and supports the current version and the one before it. The manifest's protocolVersions lists every version the connector accepts and must contain 1. A connector that refuses the API's version reads as Incompatible in the health pill. When a protocol v2 ships, a connector may list [1, 2] and serve both for a release cycle.
• Package version. The two SDK packages are stamped with the AccessPoint API version that built them and published under connectors/nuget/ at the dev/, {version}/ and latest/ paths. An API upgrade is the cue to rebuild against the matching packages, though a connector built on an older SDK keeps working as long as it speaks a protocol version the API supports. The SDK targets net8.0 and net10.0.
• Manifest version is informational (semver recommended) and shown to administrators. Bump it when behavior changes.
• What must never change once documents exist: the manifest id, the meaning of any item id (including root ids and any prefix that participates in them), and the semantics of metadataSchema keys. Provenance rows, the Captured from facet and de-duplication on connector, item id and version all depend on them. Adding capabilities, filters or metadata keys is safe, because the API re-reads the manifest hourly and on Test connection.
• Cursors should survive a connector restart and a load-balanced pair of hosts. A collection job may resume against a different instance.
• Limits can be tightened in the manifest (maxPageSize, maxContentBytes), never loosened beyond the protocol's maxima.

Checklist

• Manifest: stable reverse-DNS id, names.en, protocolVersions contains 1, a valid identityMode, capabilities and metadataSchema that match the implementation, limits within the protocol maxima, and an icon that is a Fluent name or a PNG data URI of 16 KB or less.
• Ids are opaque, up to 1024 characters, URL-safe, free of / where you can help it, never reinterpreted, and root ids are never renamed.
• Listings are in a stable order. Cursors are opaque and restart-safe. No offset paging. A pageSize above 200 is refused.
• null for unknown ids (which becomes 404). ConnectorException for access, size and source problems. No secrets or internal paths in detail.
• Content streams with length, content type, ETag and file name. Ranges are honoured (by you or the SDK). The hash is surfaced when known, on the next item read if computed while streaming.
• Search is declared only for modes you implement. Native queries are validated and read-only. The date filter is honoured when declared.
• User-check mode: listings and search trimmed per attributed user, checkAccess implemented, wantsGroups set when you need groups, per-user caches keyed by principal, and it fails closed.
• Every call logs the request id, user, case and purpose at Information level.
• Connector:AllowedCallerObjectIds is pinned to the API's managed identity and both audience forms are listed, or App Service Authentication is configured and Connector:Authentication is Host.
• HTTPS with a certificate whose SAN is the registered hostname. http:// only inside a Hybrid Connection.
• accesspoint-connector selftest passes locally and against the deployed URL. Test connection passes on a dev tenant. A capture shows Verified in Source details. A folder collection completes.
• Health answers within 10 seconds and never leaks secrets in detail.
• An operator runbook exists on the pattern of the publisher connectors' guides: prerequisites, service account, certificate, configuration keys, registration values, the vendor facts to verify, and troubleshooting.

Related Pages

• Connectors — registering, testing and looking after connectors in Settings.
• Request Documents — how staff browse, search and capture from a connector.
• Deployment — deploying and upgrading AccessPoint, including the optional Hybrid Connections parameters.
• Technical Architecture — how AccessPoint is built and where connectors fit.
• Repository connectors — the capability overview.