Skip to main content

​
What Cymph uses it for

Cymph connects to SharePoint through the Microsoft Graph API for two purposes:
  1. Importing content — browses your sites, document libraries, and pages, and reads file contents so documents can be imported as playbooks. (read) See Import a playbook.
  2. Publishing documentation — uploads a playbook’s documentation into a document library as Markdown or PDF. (write) See Deploy playbooks.
A single app registration can serve either or both purposes. If you only import, Cymph needs read access; publishing requires an additional write permission — see Permissions below.

​
Requirements

The integration requires the following information from a registered Entra ID application:

​
App registration setup

You can see the steps on how to create an Entra ID application here.
  1. In Entra ID → App registrations, create (or reuse) an app registration.
  2. Under Certificates & secrets, create a client secret and copy its value.
  3. Under API permissions, add the Microsoft Graph application permission for the access you need (see below) and grant admin consent.
  4. Note the Application (client) ID and Directory (tenant) ID from the app’s Overview page.

​
Permissions

Cymph requests tokens using the .default scope, which means it asks for no scopes of its own: the access it gets is exactly the set of application permissions already consented on your app registration. You control access entirely from the Azure side. Sites.ReadWrite.All supersedes Sites.Read.All — grant one or the other, not both. Either is an application permission (app-only, no signed-in user) and requires admin consent in your tenant.
Start with Sites.Read.All. You can raise it to Sites.ReadWrite.All later without recreating the integration — the connector picks up the broader consent on its next token request.
Graph’s Sites.Selected permission — which restricts an app to individually approved sites — is not compatible with this integration. Cymph discovers sites by calling the tenant-wide site-search endpoint, which Sites.Selected does not authorise, so both Test Connection and site listing will fail. Tenant-wide access is required.
Cymph never deletes anything in SharePoint. Publishing writes a file to the library path you select; nothing already in your document libraries is removed.

​
What Cymph reads and writes

​
Reads

File content is fetched on demand when you import a document — Cymph does not mirror or continuously sync your SharePoint content.

​
Writes

Publishing to a path that already holds a file overwrites it. Cymph returns the resulting item’s webUrl, which becomes the “navigate to the pushed playbook” link in Deploy History.

​
Publishing formats

SharePoint accepts both documentation formats: Image blocks are omitted from the Markdown format.

​
Testing the connection

Test Connection acquires a token and then searches for a single site, so it verifies both the credentials and read access:
Test Connection only exercises read access. If you intend to publish documentation, a successful test does not confirm that Sites.ReadWrite.All has been consented — the first publish attempt is what surfaces that.