Delegated access (AI hosts)

Delegated access lets an AI assistant or other MCP host connect to Filemark with a workspace member's approval and permissions.

Connection flow#

Set the host's server URL to https://api.filemark.ca/mcp. Hosts with interactive OAuth support discover the authorization server through the protected-resource metadata linked in the first 401 response, then complete the following flow.

1. The host identifies itself with the HTTPS URL of its client metadata document as client_id, or registers at /oauth2/register using RFC 7591 dynamic client registration. Filemark reads the application name and redirect URIs from the document or registration. Both methods use PKCE without a client secret. Metadata document support is advertised as client_id_metadata_document_supported.
2. The host sends the user to /oauth2/authorize with a PKCE S256 challenge and an RFC 8707 resource set to https://api.filemark.ca/mcp or https://api.filemark.ca. The user signs in, reviews the application name and requested scopes, and approves or denies access.
3. After approval, the host exchanges the authorization code at /oauth2/token for an access token and a refresh token. Token and refresh requests may omit resource or send it empty. Filemark then uses the resource the grant was authorized for. A different value returns invalid_target. Tokens issued for https://api.filemark.ca/mcp work only on the MCP server.

Scopes and visibility#

Request mcp and the scopes for the tools the host will call. Authorization is limited to the published scopes listed in the metadata document or registration. Filemark drops unpublished scopes from that list. An authorization request that names scopes outside the list, such as offline_access, is granted the others. It returns invalid_scope only when none of the requested scopes can be granted.

The consent page describes the requested scopes and shows the redirect host and, when supplied, the metadata document's host. Delegated tokens receive the approved scopes, which can include any published scope such as exports:create or clients:write, except portal:send, integrations:sync and exports:deliver. Only server integrations can hold those three.

Any workspace member can approve access to their own account. The token can access the same clients as that member, with changes to assignments or roles taking effect on the next request. Writes through the connection are recorded as that member's. See Write data.

Token lifetimes#

The user has 10 minutes after the redirect to approve access. The authorization code is single-use and expires after 60 seconds. Access tokens last up to 60 minutes.

Each refresh returns a new refresh token. Reusing an earlier refresh token revokes the entire token chain. Two refresh requests with the same token also count as reuse, such as a retry after a slow response. Send one refresh at a time and keep the newest token. If the chain is revoked, the user must approve a new connection. The connection requires a new approval 90 days after the original consent, regardless of refreshes.

Revocation#

To withdraw access, open Developer at app.filemark.ca and revoke the application under delegated access. Members can view and revoke their own connections. Owners and admins with Manage developer API permission can manage connections for everyone in the workspace.

Revocation invalidates access tokens, refresh tokens, and pending authorizations on the next request. The user must approve a new connection to reconnect. Leaving the workspace also revokes the user's connections.