Private Model Embed Integration Guide

Introduction

Private Model Embed (PME) is a solution based on a client credentials OAuth flow to securely embed private models within your organization portals instead of viewing them in the Matterport Cloud. PME allows many trusted users on your intranet, for instance, to conveniently access a private space without logging into Matterport.

Without PME, Showcase share URLs can be embedded within a webpage only if they are unlisted or public. Private Model Embed (PME) allows for the generation of a timed-access URL that can be embedded within an external webpage, all while keeping the model in a private state.

Before You Begin

To use PME, your organization must be on an Enterprise subscription and enabled for PME use. To learn more about enablement, contact our sales team.

Application Registration

After your organization has been enabled for PME, the first step is to regenerate the client secret for the OAuth application. You can do this by logging into Matterport Cloud (my.matterport.com) and going to Settings > Developer Tools > click the Reset secret button.

Note the client ID and the new secret, as these will be used by the application to generate tokens and links.

Application Integration

In this section, we’ll go over authorizing to the Matterport API, Generating a Private Link and Revoking a private access token.

Authorizing to the Matterport API

The first step for an application using PME is to procure an OAuth bearer token for use in calling the Model GraphQL API. To acquire an access token, a server-side POST request will need to be made to the following endpoint with the provided body fields and headers:

https://api.matterport.com/api/oauth/token

Here is an example cURL request:

curl --location --request POST 'https://api.matterport.com/api/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=[YOUR CLIENT ID]' \
--data-urlencode 'client_secret=[YOUR CLIENT SECRET]'

Sample response:

{
  "access_token": "[YOUR ACCESS TOKEN]",
  "token_type": "Bearer",
  "expires_in": 3599,
  "scope": "ViewPublic ViewDetails"
}

The access_token is then used in the Authorization header for the GraphQL request.

Generating a Private Link

The access token procured in the last step can be used to perform a server-side GraphQL mutation to generate a short lived token that can be used to display a private model.

The token can be used to authenticate an API request by setting the Authorization HTTP header to Bearer [YOUR ACCESS TOKEN] with the Model API Endpoint.

Model API Endpoint: https://api.matterport.com/api/models/graph

mutation createLink {
  createPrivateModelEmbedLink(
    modelId: "yyHDFKzPzvN" # The ID of the model to generate the link for
    clientId: "[YOUR CLIENT ID]"
    clientSecret: "[YOUR CLIENT SECRET]"
    validFor: "10m"
  ) {
    accessToken
    application
    link
    validUntil
  }
}

The link field in the response will be a fully formed URL that can be embedded in a page using an <iframe>.

Sample response:

{
  "data": {
    "createPrivateModelEmbedLink": {
      "accessToken": "[MODEL SCOPED ACCESS TOKEN]",
      "application": "showcase",
      "link": "https://my.matterport.com/show?m=yyHDFKzPzvN&auth=Bearer+[SHORT LIVED ACCESS TOKEN]",
      "validUntil": "2022-06-03T00:33:13Z"
    }
  }
}

Plese note, this access token will be exposed publically. For this reason, a short validity to prevent the generated url from being shareable. When the token expires, the player will no longer be able to load additional resources. For this reason, we provide methods via our SDK to refresh tokens while a user is viewing a space.

Integration with Showcase SDK

Private Model Embed (PME) was designed to work with our Showcase SDK. To use the SDK with PME, you can provide the access_token to the SDK’s connect method.

    // connect the sdk; log an error and stop if there were any connection issues
    try {
      // include the bearer token within the optional options argument:
      const mpSdk = await connect(iframe, {
        auth: token
      });
      onShowcaseConnect(mpSdk);
    } catch (e) {
      console.error(e);
    }
  })();

Handling Access Token Refreshing with the SDK

If a user is viewing a space with a short-lived access token, the token may expire, resulting in Showcase being unable to load new assets. The SDK has a createTokenRefresher method that we have provided that can seamlessly provide a new access_token to Showcase to ensure a seamless experience.

// Endpoint that returns a payload from https://api.matterport.com/api/oauth/token
const tokenEndpoint = 'https://yourdomain.com/yourapp/refresh';
const fetcher = {
  async fetch() {
    console.log('Refreshing Showcase Access Token');
    try { 
      const response = await fetch(tokenEndpoint);
    }
    catch(e) {
      console.log('Could not refresh access token', e);
    }
    const token = await response.json();
    return token;
  },
};

const initial_access_token_payload = await fetcher.fetch();
mpSdk.OAuth.createTokenRefresher(initial_access_token_payload, fetcher);

Revoking a Private Link Access Token

If for some reason an access token needs to be revoked before it’s expiration time, an additional server-side GraphQL mutation is available for this purpose:

mutation deleteToken {
  deletePrivateModelEmbedToken(
    clientId: "[YOUR CLIENT ID]"
    clientSecret: "[YOUR CLIENT SECRET]"
    accessToken: "[MODEL SCOPED ACCESS TOKEN]"
  )
}

Sample response:

{
  "data": {
    "deletePrivateModelEmbedToken": true
  }
}

Frequently Asked Questions

How long until access tokens expire?

Access token expirations are configured by the createPrivateModelAccessLink API mutation. The max amount of time that can be configured is 24 hours.

What format of times can I provide for the validFor field in the createPrivateModelAccessLink mutation?

The format accepts ISO-8601 duration format. Shorthands are also available by providing the digits and first letter of the unit of time. For example: 24h, 5m, 30s, etc.