Step 1 — Create the app registration

1. Go to the Microsoft Entra admin center and sign in as an administrator.

2. Navigate to Entra ID → Applications → App registrations and click New registration.

3. Fill in:
• Name: CaptionHub SharePoint Connector (any name works; this is what you'll see in audit logs)
• Supported account types: Accounts in this organizational directory only (Single tenant)
• Redirect URI: leave empty — CaptionHub connects server-to-server and never signs in a user

4. Click Register.

Step 2 — Copy the Tenant ID and Client ID

• Directory (tenant) ID → CaptionHub's Tenant ID field

• Application (client) ID → CaptionHub's Client ID field

Step 3 — Create a client secret

1. In the app registration, go to Certificates & secrets → Client secrets → New client secret.

2. Give it a description (e.g. CaptionHub) and choose an expiry. We recommend 24 months (the maximum).

3. Click Add, then immediately copy the Value column — not the "Secret ID" column.

⚠️ The secret value is shown only once. If you navigate away without copying it, delete it and create a new one.

⚠️ Client secrets expire. When this one expires, the CaptionHub connection will stop working until you create a new secret and update it in CaptionHub. Put a reminder in your calendar a couple of weeks before the expiry date.

Step 4 — Grant SharePoint permissions

Option A (recommended): access to one specific site only — Sites.Selected

1. In the app registration, go to API permissions → Add a permission → Microsoft Graph → Application permissions.

2. Search for and select Sites.Selected, then click Add permissions.

3. Click Grant admin consent for [your organisation] and confirm. The Status column should show a green tick.

First-time Graph Explorer setup: Graph Explorer needs your permission to manage site permissions on your behalf, and will otherwise respond with 403 Forbidden — Access denied. Open the Modify permissions tab (next to Request Body), find Sites.FullControl.All, and click Consent, approving the prompt that appears. You must be signed in as a Global Administrator or SharePoint Administrator — without one of those roles the requests below will be refused even after consenting.

• Find your site's ID. Run a request in the Graph Explorer command bar, adjusting the hostname and site name to match your Site URL. For instance, for https://contoso.sharepoint.com/sites/Marketing , you’d use:

GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/Marketing

• Grant the permission (replace the site ID in the URL, and the id/displayName with your app's Client ID and name from Step 2). Put this in the bar:

POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
Content-Type: application/json

{
  "roles": ["write"],
  "grantedToIdentities": [
    {
      "application": {
        "id": "YOUR-CLIENT-ID",
        "displayName": "CaptionHub SharePoint Connector"
      }
    }
  ]
}

Why "write"? CaptionHub publishes finished caption files (e.g. myvideo_en.vtt) into the same folder as the source video. Read-only access would allow import but publishing would fail.

Option B (simpler, broader): access to all sites — Sites.ReadWrite.All

1. API permissions → Add a permission → Microsoft Graph → Application permissions.

2. Select Sites.ReadWrite.All, click Add permissions.

3. Click Grant admin consent and confirm.

Step 5 — Connect CaptionHub

1. In CaptionHub, go to Settings → Connectors → Microsoft SharePoint.

2. Enter:
• Tenant ID and Client ID from Step 2
• Client Secret from Step 3
• Site URL — the full address of the site, e.g. https://contoso.sharepoint.com/sites/Marketing. Don't include anything after the site name — no /Shared Documents or folder names.
• Folder Path (optional) — a folder inside the site's default Documents library to scope imports to. Leave blank to browse the whole library.
• Subtitle Format — the caption file format CaptionHub will publish back (VTT by default).

3. Toggle the connector on and Save. The status indicator will confirm the connection.

Folder Path is relative to the inside of the Documents library — don't include the library name. For a folder called Videos in the Documents library, enter just Videos (not Documents/Videos). In particular, don't copy Shared Documents from your browser's address bar — that's the internal URL name of the Documents library itself, not part of the folder path. For deeper folders, separate with slashes, e.g. Videos/Incoming.

Notes and troubleshooting

• The connector uses the site's default document library (usually called "Documents"). Videos in other libraries on the same site won't appear. The Folder Path is relative to that library's root.

• Connection fails immediately after setup: admin consent and Sites.Selected grants can take a few minutes to propagate. Wait five minutes and save again.

• Connection fails with previously working credentials: your client secret has probably expired — create a new one (Step 3) and update it in CaptionHub.

• Import works but publishing captions fails: the site grant was probably created with "roles": ["read"] — re-run Part 2 of Option A with ["write"].

• To revoke CaptionHub's access at any time: delete the app registration in Entra, or just delete its client secrets.