> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cymph.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SharePoint

> Import playbooks from SharePoint documents, and publish playbook documentation back to a site.

## 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](/howto/import_playbook).
2. **Publishing documentation** — uploads a playbook's documentation into a document library as Markdown or PDF. *(write)* See [Deploy playbooks](/how-tos/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](#permissions) below.

## Requirements

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

| Field | Description |
| - | - |
| **Tenant ID** | Your Entra ID (Azure AD) tenant ID |
| **Client ID** | Application (client) ID of the registered application |
| **Client secret** | A client secret generated for the registered application |

## App registration setup

You can see the steps on how to create an Entra ID application [here](https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azuread).

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.

| If you want to | Grant | Type |
| - | - | - |
| Import content only | `Sites.Read.All` | **Application** |
| Import **and** publish documentation | `Sites.ReadWrite.All` | **Application** |

`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.

<Tip>
  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.
</Tip>

<Warning>
  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.
</Warning>

<Note>
  Cymph never deletes anything in SharePoint. Publishing writes a file to the library path you select; nothing already in your document libraries is removed.
</Note>

## What Cymph reads and writes

### Reads

| Purpose | Graph endpoint |
| - | - |
| Test the connection | `GET /v1.0/sites?search=*&$top=1` |
| List sites | `GET /v1.0/sites` |
| List a site's document libraries | `GET /v1.0/sites/{site_id}/drives` |
| Browse a library's contents | `GET /v1.0/drives/{drive_id}/root/children` |
| Browse a folder's contents | `GET /v1.0/drives/{drive_id}/items/{item_id}/children` |
| Read file metadata | `GET /v1.0/drives/{drive_id}/items/{item_id}` |
| Look up an item by path | `GET /v1.0/drives/{drive_id}/root:/{path}` |
| Download file content for import | `GET /v1.0/drives/{drive_id}/items/{item_id}/content` |
| List site pages | `GET /v1.0/sites/{site_id}/pages` |

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

### Writes

| Purpose | Graph endpoint |
| - | - |
| Upload playbook documentation | `PUT /v1.0/drives/{drive_id}/root:/{path}:/content` |

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:

| Format | What it contains |
| - | - |
| **Markdown** | The playbook's documentation blocks, rendered as Markdown |
| **Summary PDF** | The full playbook summary report — metadata, contributors, and the workflow image |

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:

| Message | Meaning |
| - | - |
| **Valid SharePoint credentials** | Authentication succeeded and the app can read sites |
| **Authorization failed** | The token was rejected (`401`) — usually a missing or unconsented `Sites.Read.All` |
| **Failed with response status *N*** | Graph answered with another error status |
| **Connection timed out** | No response within 5 seconds |
| **Target does not seem to be a SharePoint instance** | The request failed before a status could be read |

<Note>
  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.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.