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.

Integration with Showcase SDK

Private Model Embed (PME) is currently only compatible with the SDK for Embeds, not with the SDK Bundle. For inquiries about using Private Model Embed with the SDK Bundle or WebComponent, please contact Developer Support.

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 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

Header Field Value
Content-Type application/x-www-form-urlencoded
Post Body Field Value
grant_type client_credentials
client_id OAuth App ID. You can find this in the Matterport Account Settings
client_secret OAuth App secret ID. This is shown once after regenerating the secret ID in the Matterport Account Settings

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": "ut4dp7u0yq1gd15kccp176r5d",
  "token_type": "Bearer",
  "expires_in": 3599,
  "scope": "ViewPublic ViewDetails"
}

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

Using the access token procured in the last step, the Authorization HTTP header must be set to Bearer ut4dp7u0yq1gd15kccp176r5d to authorize GraphQL calls. The access token can be used to list out the organization’s models or be used with the interactive Model Picker.

Then a GraphQL mutation like the following can be issued:

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": "4bizw5azqzf40986fwm092bra",
      "application": "showcase",
      "link": "https://my.matterport.com/show?m=yyHDFKzPzvN&auth=Bearer+4bizw5azqzf40986fwm092bra",
      "validUntil": "2022-06-03T00:33:13Z"
    }
  }
}

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

mutation deleteToken {
  deletePrivateModelEmbedToken(
    clientId: "[YOUR CLIENT ID]"
    clientSecret: "[YOUR CLIENT SECRET]"
    accessToken: "4bizw5azqzf40986fwm092bra"
  )
}

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.

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.