Migrating a developer app

Miro developer apps (settings)

Miro developer apps are associated with a particular developer team within a Miro account when they’re created. When an app is created, a unique set of credentials is created: Client ID and Client Secret.

These credentials are unique and are what the OAuth2.0 flow for the application will ingest when authorizing the app externally. This means that external applications that make requests associated with this Client ID and Client Secret will be beholden to that particular Miro app’s settings (URL for Web SDK, Redirect URL for REST API) and permissions (OAuth scopes).

Best practices for creating an app

When creating a developer app, consider the team and account you’re creating the app under. If you’re a developer working on a team within an organization, you may want to consider who else should be part of your developer team and Miro account when creating the app, and you may want to associate it with a general/service account (e.g., integrations@company.com).

Staging app

Some developers find it helpful to create two identical apps (same app url, redirect url, permissions) with separate Client IDs for “staging” and “production”.

This can be helpful if you’re developing a more complex integration or application and would like to see how certain changes in your app interact with Miro in your testing.

Creating two apps with the same settings and URLs will ensure the interaction with Miro’s APIs or SDK is identical, allowing you to treat one app (“staging”) as a testing ground before making any adjustments to the Miro settings in your final app (“production”).

While this is not necessary, it can be helpful for developers who are conscious of testing out different permissions (scopes) or URLs with their external application, and only having to change the environment variables in your local code (e.g., Client ID, Client Secret, Redirect URL for REST API integrations).

Common migration scenarios

There may be times where you need to migrate an app from one team or account to another. Some common scenarios:

• The original app was created under a team or account that isn’t the account you wish to use for managing the integration or app going forward
• The original developer of the app has left the company and the settings aren’t available to other members of the team

How to migrate an app

To migrate an app from one team to another, you can quickly recreate the same app in the desired destination by copying the app manifest of the original app. This will ensure the app has the same settings behavior and is identical to the original app, aside from the unique Client ID. Note: This will require updating the Client ID and Secret in your external application / local code.

To do so, follow these steps:

1. Login to the account and team that the original app currently exists in.
2. Navigate to the app settings in Miro (Developer Hub > Your Apps > Edit app settings) for the app you wish to migrate
3. Click Edit in manifest
   1. This will expose the app manifest
      1. 
4. From the editor, copy all code:
   1. 
5. If you’re migrating the app to a new account, log out of the existing account and login to the account and team that you wish to migrate the app to. Note: This should be a developer team.
6. Create a new app under your desired team and account.
7. From the new app, click Edit in manifest
   1. This will expose the app manifest
8. Paste in the code that you copied from Step 4, hit Save.
9. In your external application, replace your environment variables as needed with the updated Client ID and Client Secret for your “migrated” app.

Special requests

In certain circumstances, it may be necessary for us to manually transfer an app for you. For example, if your app has already been authorized by several end users and you don’t want to break those connections by leveraging a new app/Client ID.

Or if you’re unable to access the original app and the team it was created under, we may similarly be able to help migrate the app manually. (For example, the original developer left the company, and you need help moving the app to a team that you can access.)

For these situations, please open a ticket with our support team under Miro for Developers > Miro for Developers / Other and provide the following details: App Client ID, original account and team IDs, new account and team IDs.