API documentation

SharePoint

Stonewake runs inside your SharePoint pages and in Microsoft Teams, and files its reports into your document libraries. Each part is set up by your own administrators. A page shows Stonewake through the standard Embed web part or through the Stonewake app for SharePoint and Teams, and report and committee pack PDFs reach a library either through Stonewake's own delivery or through a Power Automate flow. This page is the guide for the administrators who set them up.

Stonewake on a SharePoint page

How it works

  • A workspace administrator lists the SharePoint sites that may show Stonewake, each by its exact address, for example https://yourbank.sharepoint.com. Only those sites can frame the workspace's embed address. Every other page of Stonewake refuses to be framed by any site, with frame-ancestors 'none' and X-Frame-Options: DENY.
  • The list is empty for every workspace until an administrator adds a site. An address with a wildcard such as *.sharepoint.com is refused, because it would admit the pages of every Microsoft customer. So is an address with a path, a port or plain http.
  • Each change to the list is written to the audit trail of your workspace with the list before and after.
  • Members sign in with their own Stonewake account. Sign in opens in a separate window on Stonewake's own address, because Microsoft and most identity providers refuse to show a sign in page inside a frame. The window hands the session to the Stonewake page in the frame and closes. The message travels only to Stonewake's own address, so the SharePoint page that holds the frame receives nothing.
  • Inside the frame the session lives in memory only. No cookie and no browser storage holds it, and reloading the SharePoint page asks for a sign in again.
  • A sign in to a different workspace is refused and ended at once, so a page that one workspace allowed never shows another workspace's data.
  • Workspace administration does not open inside the frame. API keys, members, the sign in settings and this list of sites open in Stonewake's own tab, and the API refuses those changes when they are sent from a framed page.

Set it up

  • Step 1. In Stonewake, open Workspace settings, then SharePoint pages, then Manage SharePoint sites. Add the address of your SharePoint site, https://<tenant>.sharepoint.com. A OneDrive address, https://<tenant>-my.sharepoint.com, is a separate site and needs its own entry.
  • Step 2. Copy the Address for the Embed web part, https://app.stonewake.ai/embed/<embed id>. The embed id is a random key for your workspace and names no bank or person.
  • Step 3. A site collection administrator allows Stonewake on the site under Site settings, HTML Field Security, by adding app.stonewake.ai to the domains whose content may be embedded. Microsoft describes the setting in Allow or restrict the ability to embed content on SharePoint pages.
  • Step 4. On a page, add the Embed web part and paste this embed code with the address from step 2, <iframe src="https://app.stonewake.ai/embed/<embed id>" width="100%" height="900"></iframe>. The web part takes a plain address only from sites that offer their own embedding service, so Stonewake goes in as embed code. Microsoft describes the web part in Use the Embed web part. Publish the page.
  • Step 5. Members open the page and choose Sign in. Their browser must allow the SharePoint site to open a window.

Requirements

  • The page is on SharePoint Online, so its address starts with https:// and ends with .sharepoint.com.
  • The frame may open a window. A frame wrapped in a sandbox that blocks pop ups cannot show the sign in window.
  • With single sign on for your workspace, the sign in window offers Continue with your organization beside the password sign in.
  • The Stonewake app for SharePoint and Teams is a separate integration with its own setup, described in the next part of this page.

The Stonewake app for SharePoint and Teams

How it works

  • The Stonewake app is one SharePoint Framework package, stonewake.sppkg. It adds a Stonewake web part to SharePoint pages, and a Stonewake app to Microsoft Teams that opens as a personal app or as the tab of a channel. Both show the person's team, the portfolio summary, the five latest status changes and a link into Stonewake.
  • The person is signed in through SharePoint with their Microsoft account. The web part asks Microsoft, through SharePoint's own client, for a token for the application Stonewake API with the permission Workspace.Read, and reads https://api.stonewake.ai/v1 with it. No Stonewake password and no sign in window are involved.
  • Stonewake accepts such a token only from the Microsoft tenant your workspace proved for single sign on, only for Stonewake API with Workspace.Read, and only on /v1. The token reads as the person's own Stonewake login, the one whose Microsoft sign in stated the same Microsoft object id, and never by matching an email address. A person without such a login sees a short notice and no data.
  • The app only reads. Each read shows what a viewer of the person's own team sees, whatever their role in the dashboard, because SharePoint grants an API permission to every SharePoint Framework solution in your tenant.
  • Only your own SharePoint address may call Stonewake from the browser. Stonewake adds it for your workspace once Microsoft's public record shows that it belongs to your tenant, and every other site gets no answer it can read.
  • Stonewake receives the token and nothing else from SharePoint, no page, no file and no list.

Set it up

  • Step 1. Set up single sign on with Microsoft Entra ID for your workspace. Each person signs in to Stonewake with Microsoft once, so that their login holds their Microsoft object id.
  • Step 2. Send your Stonewake contact the address of your SharePoint, https://<tenant>.sharepoint.com. Stonewake checks it against Microsoft's public record, adds it for your workspace and sends you the package stonewake.sppkg.
  • Step 3. A SharePoint administrator opens the Apps site, selects Upload and chooses stonewake.sppkg. In the Enable app panel, select Enable this app and add it to all sites, and Add to Teams for the Teams app. Microsoft describes the Apps site in Manage apps using the Apps site.
  • Step 4. An administrator with the Application Administrator role or higher opens API access in the SharePoint admin center and approves the pending request for Stonewake API with Workspace.Read. The approval adds Stonewake API to your Microsoft Entra ID as an enterprise application of its own, beside the Stonewake application your team created for single sign on. Microsoft describes the page in Manage access to Microsoft Entra ID-secured APIs.
  • Step 5. A Teams administrator allows the Stonewake app in the Teams admin center, in your custom app settings and app permission policies. Microsoft describes the settings in Manage custom app policies and settings.
  • Step 6. Page editors add the Stonewake web part to a page. People add Stonewake in Teams as a personal app, and a channel owner can add it as a tab.

Requirements and removal

  • Your workspace signs in with Microsoft single sign on, and the SharePoint address is the root address of your tenant, https://<tenant>.sharepoint.com. A OneDrive address is refused.
  • Your conditional access policies can include Stonewake API like any other application.
  • To remove the app, remove it from the Apps site, revoke Workspace.Read for Stonewake API under API access, and ask your Stonewake contact to remove your SharePoint address. A token issued before the revocation ends with its own lifetime, at most two hours.

Reports and packs in a SharePoint library

The documents

Five /v1 endpoints answer the same PDF documents the dashboard downloads (see API reference).

  • The deal report and the deal committee pack, by the deal id GET /v1/deals serves.
  • The counterparty report and the counterparty pack, by the registry id GET /v1/entities serves.
  • The company profile, by the graph node id GET /v1/search hits carry.

A pack and a company profile take locale=de or locale=en; without it they use your workspace's pack language.

Delivered by Stonewake

Stonewake saves the documents into the library itself, through Microsoft Graph and an app your administrators register in your own Microsoft Entra directory. This way needs no Power Automate licence and no API key. Your Stonewake contact enables library delivery for your workspace on request.

How Stonewake delivery works

  • Your Entra administrator registers an app for Stonewake in your directory and gives it the Microsoft Graph application permission Sites.Selected with admin consent. With Sites.Selected alone the app reaches no site at all.
  • Your SharePoint administrator then grants that app write on exactly one site. Microsoft describes the steps in Overview of Selected permissions in OneDrive and SharePoint. Stonewake writes into that site and nowhere else, and your administrators can withdraw the grant at any time.
  • A workspace administrator of Stonewake enters the directory id, the application id, the client secret, the site, the library and the folder. The secret is sealed in Stonewake's credential vault, under a key that never enters the database, and is never shown again.
  • Each library belongs to one team of your workspace. Stonewake renders its documents with that team's reading rights, the same rights a key of that team has, so a deal of another team is never filed.
  • The documents are the five documents above, byte for byte, under the file name a download gives them, which carries the date. A document filed twice on one day becomes a new version of the same file.

Set up Stonewake delivery

  • Step 1. In the Microsoft Entra admin center, open App registrations and choose New registration. Name it Stonewake library delivery and keep Accounts in this organizational directory only. Note the Application (client) ID and the Directory (tenant) ID on its overview page. Microsoft describes the page in Register an application.
  • Step 2. Under API permissions, add Microsoft Graph, Application permissions, Sites.Selected, then choose Grant admin consent for your organization.
  • Step 3. Under Certificates and secrets, add a client secret and copy its value, which Entra shows only once. Choose the expiry your policy allows and note the date, because deliveries stop when the secret expires.
  • Step 4. A SharePoint administrator grants the app write on the one site, for example in Graph Explorer. Read the site id with GET https://graph.microsoft.com/v1.0/sites/<tenant>.sharepoint.com:/sites/<site>, then send POST https://graph.microsoft.com/v1.0/sites/<site id>/permissions with the body {"roles": ["write"], "grantedToIdentities": [{"application": {"id": "<application id>", "displayName": "Stonewake library delivery"}}]}. Microsoft describes the request in Create permission. Sending it needs Sites.FullControl.All and a role such as SharePoint Administrator.
  • Step 5. In Stonewake, open Workspace settings, then SharePoint libraries, Manage SharePoint libraries and Connect a library. Enter a name, the team whose documents the library receives, the directory id, the application id, the client secret value, the site address https://<tenant>.sharepoint.com/sites/<site>, the library as SharePoint names it (Documents for the standard library) and a folder in it. Create the folder in the library first, or leave the field empty for the top of the library.
  • Step 6. Choose Check connection. Stonewake signs in as the app, finds the site, the library and the folder, and saves one small text file, Stonewake connection check.txt, into the folder. The check passes only when that file is written.
  • Step 7. Under Edit, add each document with the id from the address of its deal or company page, choose the schedule, every day or every Monday at 06:00 UTC, and save. Deliver now files them at once.

What Stonewake delivery writes and records

  • Stonewake calls only login.microsoftonline.com for the app's token and graph.microsoft.com for the site, the library, the folder and the upload. It never follows an address an answer carries.
  • Every document filed writes one library_document_delivered row to the audit trail of your workspace with its size and its SHA-256 checksum. A document Stonewake tries and does not file writes one library_document_failed row with its reason. A delivery that Microsoft holds up or refuses, or that reaches its time limit, writes one library_delivery_failed row. Every change of a library, every check and every Deliver now is written there too.
  • A document the team cannot read is not filed and shows as not readable for this team.
  • A library takes at most 25 documents and 100 uploads a day. The libraries of one workspace are delivered one after another, and a delivery ends after 10 minutes at the latest. A delivery that fails, for example because Microsoft is busy or answers too slowly, is tried again 30 minutes later and then 4 hours later, later only when Microsoft asks for a longer wait, and never after the library's next scheduled time. A library without a schedule is tried again with the next Deliver now. After three failures in a row the library waits until an administrator checks the connection again.
  • In a library that labels new files with a sensitivity label, Microsoft does not let an app replace a labelled file. A document filed earlier the same day then stays as it is, and the later delivery records the refusal.
  • A delivery never drafts a new summary and makes no model call, like every download below.
  • A new site, library or folder needs a new check before the next delivery, and a delivery under way stops before its next upload when the site, library, folder or team changes. A refused sign in, for example an expired secret, stops the deliveries of that library until a check passes again.
  • Disconnect asks for a confirmation, then ends the library for good, revokes its secret in the vault and stops a delivery under way before its next upload. Remove the grant of the app on the site, or delete the app registration, to end it on your side as well.

The key

A workspace administrator creates an API key with Can also download reports and packs as PDF, under Workspace settings, API keys (or report_downloads set to true, see Keys and access management). Without that scope a download answers 403. The key reads exactly its one team, so a deal of another team answers 404. Keep the key in a secure input of your flow or in your organization's key store, never in a document or a page.

Save a pack with Power Automate

The other way, without an app registration in your directory. The flow fetches each document with a reports key and saves it with the SharePoint connector.

  • Step 1. In Power Automate, create a scheduled cloud flow, for example every Monday at 07:00, or an instant flow.
  • Step 2. Add the action HTTP. Method GET. URI https://api.stonewake.ai/v1/deals/<deal id>/pack.pdf?locale=de. One header, Authorization with the value Bearer followed by the key. The HTTP action is a premium connector in Power Automate.
  • Step 3. In the settings of the HTTP action, switch on Secure inputs and Secure outputs, so the key and the document stay out of the flow's run history.
  • Step 4. Add the SharePoint action Create file. Site Address is your site. Folder Path is the library folder, for example /Shared Documents/Credit committee. File Name is for example Committee pack <deal id> @{utcNow('yyyy-MM-dd')}.pdf. File Content is the Body of the HTTP action.
  • Step 5. Save the flow, run it once and open the file in the library.

For several deals, keep their ids in a SharePoint list and wrap steps 2 and 4 in Apply to each over the list's items. A report or a profile works the same way with its own address from the list above.

Answers and records

  • 200 with Content-Type: application/pdf and the file name in Content-Disposition.
  • 401 for a missing, revoked or expired key. 403 for a key without the reports scope. 404 for an id the key cannot read.
  • 429 above the rate limit and 503 with Retry-After while rendering is busy. The HTTP action's default retry policy repeats both.
  • A download never drafts a new summary. A summary drafted and checked earlier is used, otherwise the document says it carries none, and a download makes no model call.
  • Each download is written to the audit trail of your workspace as report_generated or pack_generated, with the key that asked for it.
  • A company profile or a counterparty pack that prints officers or owners also writes one v1_person_read row with the persons' ids, like every /v1 read of person data.