Mode Integration

The Stemma Mode integration accesses the Mode Discovery API. This API is distinct from regular Mode API: it is much more performant but only contains a subset of the available endpoints. This means Stemma is able to access only metadata about reports, not the report runs/results. Stemma also accesses the regular REST API to augment the information retrieved from the Discovery API. In all, there are four values required by Stemma:

1. Your organization name in Mode
2. The access token to access the REST API
3. The password token to access the REST API
4. A signature token to access the Discovery API

Optionally, if you would like Stemma to only extract metadata from specific Mode spaces you may also provide Stemma a list of the spaces to include.

Creating the Access Token & Password Token

You can learn about how to create this access here (https://mode.com/developer/api-reference/authentication/).

The access token and password token allow Stemma to augment the information within the Discovery API with the regular REST API to unlock two additional capabilities:

1. The ability to link your dashboards to the underlying tables in your warehouse which are used to serve the dashboards.
   • Stemma will use the general Mode API for datasources to retrieve your data source information to find out the name of the database (you may use, PUBLIC, mktg, etc.) as well as the type of data source (e.g. Snowflake, Redshift, etc.) in order to apply the proper SQL parsing semantics.
2. The ability to rank your dashboards by the number of times the dashboard has been viewed in the past 90 days.
   • Stemma will use the general Mode API for reports API to retrieve an accurate view count.

Creating the Signature Token

To authenticate with the Mode Discovery API a signature token must be created. This signature token can be created by running a curl command using the account’s REST API access token and password secret. The following code is a snippet from Mode that has been slightly adjusted to create a signature token that Stemma can use. Make sure to replace {organization} , {your-access-token} and {your-access-secret} with the appropriate values (organization can be found in the URL when you visit Mode, e.g. https://app.mode.com/<organization>/spaces). Visit the Mode documentation for information on creating the api-key and api-secret.

curl --location --request POST 'https://app.mode.com/batch/{organization}/signature_tokens' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--user '{access-token}':'{your-access-secret}' \
--data-raw '{
    "signature_token": {
        "name": "stemma-api-token",
        "expires_at": "2024-10-02T21:00:00+0000",
        "auth_scope": { "authentication_for" : "batch-api", "authorization_type": "read-only" }
    }
}';

Please note, if this does not work it likely means you do not have permissions. Please contact Mode support with help creating a read-only signature token.

APIs used

APIs are listed in the table below. In the table below, Data Extracted is the data we actually store from the API (and may change as we add functionality). Risks highlights any potentially-sensitive information in the API (whether or not we actually store it).

Please note, that the “Report Stats” endpoint is not enabled by default in mode, so functionality coming out of it may not be available, until the endpoint is enabled.

Name	Docs	Data Extracted	Risks
Charts	https://mode.com/developer/discovery-api/analytics/charts/	Chart name, type, query id	Low: contains employee email addresses
Reports	https://mode.com/developer/discovery-api/analytics/reports/	Execution times, dashboard names, dashboard descriptions, creation/last modified times, owner email addresses,	Low: contains employee email addresses
Report Stats	https://mode.com/developer/discovery-api/analytics/report-stats/	Usage counts	Low[1]
Queries	https://mode.com/developer/discovery-api/analytics/queries/	Name, Raw SQL	Moderate[2,3]
Memberships	https://mode.com/developer/discovery-api/analytics/members/	Mode usernames	Low: contains employee email addresses
Reports: detailed	https://mode.com/developer/api-reference/analytics/reports/	Dashboard view counts	Low: contains metadata about the report itself, not the underlying executions of the report
Data Sources	https://mode.com/developer/api-reference/management/data-sources/	Mode data source name and data source type.	Low: contains access to information about the data source. Stemma should separately have access to this information but this API access is required to link a mode dashboard to a specific database.

Notes

Here are some additional notes about possibly sensitive information we may receive from Mode

1. Dashboard execution times are non sensitive on their own, although it is possible to infer NPMI from who is running which dashboard queries at precise times. Stemma only displays aggregated forms of this information, but stores it disaggregated.
2. Query names may contain NPMI (e.g. a query titled “EMEA Expansion Potential”, when the company hasn’t announced its intention to expand into EMEA).
3. Raw SQL queries may contain sensitive information (PII), typically in the form of filter clauses. This is generally not allowed under most security policies especially under Open Collections, however, it is a possibility. By default, these SQL statements will be shown to users in Stemma.

Configuring Your Stemma Connection