Authorization

A Connect grant binds one application installation, one canonical manifest, one collection, one scope, and an exact operation set. The collection authority checks the grant again for every request.

One application installation may retain several independent grants. The manager lists them with connections(); every operation is made through a MdbaseConnection bound to one collection ID.

Use the flow selected by the manifest

Web and native-shell manifests use an authorization-code redirect with PKCE. authorize() navigates away, and the callback route calls completeAuthorization().

A distribution: "portable" manifest uses short-code device authorization with PKCE and a P-256 application key.authorize() opens the approval page, polls at the server interval, and resolves with the collection-bound connection after approval.

const controller = new AbortController();

const { connection } = await connect.authorize({
  operations: ["describe", "read", "query"],
  onDeviceCode: ({ userCode, verificationUriComplete }) => {
    renderApprovalCode(userCode, verificationUriComplete);
  },
  signal: controller.signal
});

The abort signal stops polling and discards the unapproved in-memory key. Use openVerification when a shell owns the approval window. See the portable HTML application guidefor the complete downloaded-file boundary.

Choose operations by feature

Request additional operations at the point of use

Begin with the operations used by the current feature. Inspect the current gap when a user opens an editing or administration feature.

const required = ["read", "query", "update"] as const;
const capability = connection.authorizationCapabilities([...required]);

if (!capability.sufficient) {
  await connection.requestOperations([...required], {
    returnTo: collectionLocation.authorizationReturnTo()
  });
}

requestOperations() is a no-op when the current grant is already sufficient. Otherwise it asks for the least-privilege union of the existing operations and the new requirements.

Render current connection state

const stop = collectionLocation.onChange(({ connection }) => {
  if (!connection) {
    renderDisconnected();
    return;
  }

  const info = connection.info();
  renderConnection({
    collectionId: info.collectionId,
    route: info.route,
    operations: info.operations
  });
});

// Call stop() when the owning UI is destroyed.

The route is direct, relay, or hosted. Display it as status information. The SDK selects the route. The browser location subscription also reports back and forward selection changes. A null connection means the bookmarked collection has no usable authorization.

Use structured recovery actions

MdbaseConnectError includes a machine-readable code, current grant information where relevant, and a recovery action:retry, reauthorize, refresh,resolve_outcome, fix_request, or none.

try {
  await connection.update(input);
} catch (error) {
  if (error instanceof MdbaseConnectError) {
    switch (error.recovery) {
      case "reauthorize":
        await connection.requestOperations(["update"]);
        break;
      case "refresh":
        await refreshVisibleState();
        break;
      case "resolve_outcome":
        await connection.resumePendingMutation(input);
        break;
    }
  }
  throw error;
}

Disconnecting an application

connection.forget() clears only that collection's local authorization state. manager.forgetAll() clears the saved set. Neither replaces user-controlled revocation at the collection authority. Provide a clear path to the Connect controller when a user needs to review, narrow, pause, or revoke a grant.