Edmund AI Documentation
/SETUP GUIDES

Part A — Initial setup

Registering an application in Microsoft Entra ID, granting it read access to one site, and entering the four connection values in Edmund.

Part A is performed once, by the customer’s administrators. It produces four values, which an Edmund Administrator then enters in the application; from there on everything is self-service.

Two roles are required: a Global Administrator or Privileged Role Administrator to consent the permissions in step 3, and a SharePoint Administrator to create the site grant in step 4.

1. Register an application in Entra ID

  1. Open App registrations

    Go to entra.microsoft.com, then Applications → App registrations → New registration.

  2. Register the application

    Name it edmund-sharepoint-readonly. Set Supported account types to Single tenant. Leave the redirect URI empty — the application signs in as itself, not as a user.

    Click Register.

  3. Copy the identifiers

    From the Overview page, copy the Application (client) ID and the Directory (tenant) ID. Use the copy button on each field. The Object ID on the same page is not interchangeable with either.

2. Create a client secret

Go to Certificates & secrets → New client secret. Set a description and an expiry; 12 months balances rotation effort against risk.

Warning

Copy the secret value immediately. Azure shows it once. The Secret ID next to it is not the secret and will not authenticate.

Record the expiry date. An expired secret stops synchronisation with no error in Edmund — documents simply stop arriving. Replacing it is part B, chapter 13.

3. Grant Microsoft Graph permissions

Go to API permissions → Add a permission → Microsoft Graph → Application permissions. Not Delegated — there is no signed-in user.

Choose one:

PermissionScope
Sites.SelectedRecommended. No access until granted, site by site
Sites.Read.AllRead access to every SharePoint site in the tenant
Warning

Files.SelectedOperations.Selected appears alongside these and its description reads like a narrower version of the same idea. It is a different model — access to individual files shared with the application — and the connector cannot work through it.

Click Grant admin consent. Without consent the application has no access regardless of what the list shows. The permission is in place when Sites.Selected is listed as Granted for <organisation>.

4. Grant access to one site

Note

This step applies to Sites.Selected only. With Sites.Read.All the permission is effective after admin consent, and covers every site.

The grant is per site, and it covers that site’s whole content. A site created for Edmund therefore keeps the grant narrower than a grant on the tenant root site, which would expose the intranet library as well.

Sites.Selected grants nothing on its own. Three conditions must hold: the permission is consented, a grant exists on the site, and the token carries the scope.

Both calls are made in the Graph Explorer, signed in as an administrator of the tenant, which must be consented to Sites.Read.All and Sites.FullControl.All for its own delegated access.

  1. Find the site identifier
    GET https://graph.microsoft.com/v1.0/sites/{hostname}:/sites/{site-name}

    The id in the response is the site ID — a hostname and two GUIDs separated by commas, used whole in the next call.

  2. Grant read access
    POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
    Content-Type: application/json
    
    {
      "roles": ["read"],
      "grantedToIdentities": [{
        "application": {
          "id": "{application-client-id}",
          "displayName": "edmund-sharepoint-readonly"
        }
      }]
    }

    201 Created confirms the grant. The response echoes the application’s display name, which confirms the identifier resolved to the intended application.

To revoke the grant later:

GET https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
DELETE https://graph.microsoft.com/v1.0/sites/{site-id}/permissions/{permission-id}

204 No Content confirms the deletion. Deleting the grant revokes access to that site; removing the consent in Entra ID revokes access to every site at once.

5. Find the drive ID

Edmund needs the identifier of the document library that holds the documents.

GET https://graph.microsoft.com/v1.0/sites/{site-id}/drives

The library appears as Documents; its id is the drive ID. Where a site has several libraries, send the one holding the monitored folders.

The application can also read it with its own credentials, which verifies the secret and the grant at the same time:

import msal
import requests

TENANT_ID = "YOUR_TENANT_ID"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
SHAREPOINT_HOST = "contoso.sharepoint.com"
SITE_NAME = "sites/edmund-documents"

GRAPH_BASE = "https://graph.microsoft.com/v1.0"


def acquire_token(tenant_id: str, client_id: str, client_secret: str) -> str:
    app = msal.ConfidentialClientApplication(
        client_id,
        authority=f"https://login.microsoftonline.com/{tenant_id}",
        client_credential=client_secret,
    )
    result = app.acquire_token_for_client(
        scopes=["https://graph.microsoft.com/.default"])
    if "access_token" not in result:
        raise RuntimeError(f"Failed to acquire token: {result.get('error_description')}")
    return result["access_token"]


def get_site_id(token: str, host: str, site_name: str) -> str:
    url = f"{GRAPH_BASE}/sites/{host}:/{site_name}"
    resp = requests.get(url, headers={"Authorization": f"Bearer {token}"}, timeout=30)
    resp.raise_for_status()
    return resp.json()["id"]


def get_drive_id(token: str, site_id: str) -> str:
    url = f"{GRAPH_BASE}/sites/{site_id}/drive"
    resp = requests.get(url, headers={"Authorization": f"Bearer {token}"}, timeout=30)
    resp.raise_for_status()
    return resp.json()["id"]


if __name__ == "__main__":
    token = acquire_token(TENANT_ID, CLIENT_ID, CLIENT_SECRET)
    site_id = get_site_id(token, SHAREPOINT_HOST, SITE_NAME)
    print("Site ID: ", site_id)
    print("Drive ID:", get_drive_id(token, site_id))

It needs msal and requests:

pip install msal requests

If the script is inconvenient, the drive ID can also be read in the Graph Explorer with the call above.

6. Entering the connection in Edmund

Success

Four values, and the expiry date of the secret in your own records.

An Administrator opens Settings → Connections → SharePoint in Edmund and enters:

FieldSource
Tenant IDDirectory (tenant) ID, step 1
Client IDApplication (client) ID, step 1
Client secretStep 2
Drive IDStep 5

Edmund verifies the values against the library before saving. A wrong value is rejected on the spot, with nothing written; a saved connection is therefore one that has been proven to work. The secret is never displayed back afterwards — the page only shows that one is held.

Note

The client secret does not leave your organisation. It is entered directly in Edmund by your own administrator, not sent to us. Nothing needs to travel over email or any other channel.

Record the expiry date of the secret so its replacement can be planned; replacing it is part B, chapter 13.

Which folders each project monitors is set in the same place, or on the Integrations card in a project’s settings — part B, chapter 11. It needs no involvement from Edmund either.