Skip to main content

Invite Others to Test Your Integration

SmartThings Schema invitations allow you to install your Schema integration without publishing it to the SmartThings catalog, and to invite other users to test your Schema integration. As you iterate and continue to develop your Schema integration, existing users will automatically take advantage of your updated integration - no action is required from either you or your users.

Before getting started, you will need:

  • An existing SmartThings Schema integration.
  • The latest version of the SmartThings CLI installed and signed in using the Samsung account associated with your Schema integration. If you have not previously authorized the CLI to access your SmartThings account, you will be prompted to do so when running the commands listed below.
tip

Check out an example of using the invitations feature in the Samsung developer blog.

Create and Share an Invitation ​​

Get started with an interactive session in the SmartThings CLI. The CLI will list all Schema integrations associated with your SmartThings account and walk you through the invitation creation process:

$ smartthings invites:schema:create

If you already know the ID of your Schema app, you can specify it on the command line (this is particularly helpful if you want to create more than one invitation):

$ smartthings invites:schema:create --schema-app myapp_id

The CLI will prompt you to select an existing app and will ask you to provide the following parameters:

  • Description (optional): your description will be displayed to users when viewing your invitation.
  • Accept Limit (optional): Limit the number of installations. If you do not specify a limit, your invitation will automatically be limited to a maximum of 500 installs.

After following the prompts in the CLI, a new invitation will be created for you: ​

──────────────────────────────────────────────────────────────────────────────────────────────
 Invitation Id    0aa97541-0d89-4ff7-b8d6-3553b07a28b1
 Description      my invitation description
 Expiration       2023-10-31T19:48:55.000Z
 Acceptances      0
 Accept URL       https://invitations.smartthings.com/schemaApp/INVITATION_ID
 Schema App Id    viper_98fdced9-1a7a-48bd-a226-f787d0adc653
 Schema App Name  My ST-Schema App
──────────────────────────────────────────────────────────────────────────────────────────────

​ Send the Accept URL to the users you want to invite to use your SmartThings Schema app. Anyone with this URL and a SmartThings account can install your SmartThings Schema integration.

When a user accesses your Accept URL, they will be directed to a landing page with your Schema integration logo, support email, and description as defined when you originally created your Schema integration. The user will be prompted to select a Location associated with their SmartThings account and to authorize SmartThings to access your Schema integration.

important

Invitations automatically expire after 30 days. After your invitation expires, new users will not be able to join your integration with the associated Accept URL. Your Schema app will continue to function for existing users, but will not allow existing users to reinstall your app. A new invitation can be generated at any time.

Check the Status of an Invitation​

View your existing invitations:

smartthings invites:schema

If you know your invitation ID, you can specify this directly to view the accept URL link, number of acceptances, and more:

$ smartthings invites:schema 0aa97541-0d89-4ff7-b8d6-3553b07a28b1
─────────────────────────────
 Invitation Id    0aa97541-0d89-4ff7-b8d6-3553b07a28b1
 Description      my invitation description
 Expiration       2023-10-31T19:48:55.000Z
 Acceptances      0
 Accept URL       https://invitations.smartthings.com/schemaApp/INVITATION_ID
 Schema App Id    viper_98fdced9-1a7a-48bd-a226-f787d0adc653
 Schema App Name  My ST-Schema App  
─────────────────────────────

Delete an Invitation​

Deleting an invitation will nullify the Accept URL, preventing new users from installing your Schema app. Existing users will be unable to reinstall your Schema app or change the installed app location.

caution

Existing installations of your shared Schema app will not be affected. To prevent existing users from continuing to use your Schema app, send a proactive discoveryCallback or stateCallback with the SmartThings Schema globalError.errorEnum: INTEGRATION-DELETED. The globalError can also be provided in a Schema response.

To delete an invitation:

smartthings invites:schema:delete

and select a previously created invitation. If you know your invitation ID, you can specify this directly: ​

$ smartthings invites:schema:delete 0aa97541-0d89-4ff7-b8d6-3553b07a28b1
Invitation 0aa97541-0d89-4ff7-b8d6-3553b07a28b1 revocation requested. (This may take a few moments to complete.)