README-ngrok.md

OAuth 2.0 Node.js App Example (With Ngrok)

This app shows how to implement the OAuth 2.0 authorization code grant flow (using ngrok for our redirect URL) to make Miro REST API calls.

👨🏻‍💻 App Demo

oauth-demo.mp4

📒 Table of Contents

• Included Features
• Tools and Technologies
• Prerequisites
• Associated Developer Tutorial
• Run the app with ngrok
• Folder Structure
• Contributing
• License

⚙️ Included Features

• Miro REST API
  • GET /boards/{board_id}
  • POST /oauth/token

🛠️ Tools and Technologies

• Express
• Axios

✅ Prerequisites

• Create a new app in Miro
• You have a Miro account.
• You're signed in to Miro.
• Your Miro account has a Developer team.
• Your development environment includes Node.js 14.13 or a later version.
• All examples use npm as a package manager and npx as a package runner.
• Install ngrok.

📖 Associated Developer Tutorial

To view a more in depth developer tutorial of this topic see the OAuth 2.0 Miro tutorial on Miro's Developer documentation.

🏃🏽‍♂️ Run the app with ngrok

1. Run npm install to install dependencies.

2. Run ngrok http 3000 and copy the forwarding address. It should look something like:

https://1ce8-45-94-204-74.ngrok-free.app. This will be the value for redirectURL in your .env file.

3. Rename the .sample.env file to .env and then fill in the values.

To find your client ID and secret, go to Your apps, and then select the app you just created to access its settings page. On the app settings page, go to App Credentials, and copy the app Client ID and Client secret values. To find your boardId Go to your desired Miro board, copy the board ID from the URL, and paste it to your .env file boardId variable. For more info on how to get your board ID, see the community question. The redirectURL is just the forwarding address from step 2. Once your .env file is completed, it should look similar to this:

clientID=12345678910
clientSecret=12345678910abcdefg
redirectURL=https://01-11-11-2011-74.ngrok-free.app
boardId=abcdefghik=

4. Open the app manifest editor by clicking Edit in Manifest.
   In the app manifest editor, copy and paste the following yaml code:

# See https://developers.miro.com/docs/app-manifest on how to use this
appName: OAuth2.0 with NodeJS
redirectUris:
  - https://[YOUR_NGROK_URL].ngrok-free.app
scopes:
  - boards:read

Note, your redirectUris should be different than mine, it's just the forwarding address from ngrok. Make sure both are the same in your app settings and in your .env file

5. Run npm run start to start the server.

6. Once your server is running, copy the installation URL of your app under Share App in the app settings UI and paste it in your browser. This should take you to the Miro OAuth page. Select your dev team, and then click Add. You can see this step done in the App Demo at the top of the README.

7. This should take you to your redirect URL now. You should now see Hello, World! and Miro API Response: in your browser. Great job! You've completed this app example! You can see this step done in the App Demo at the top of the README.

🗂️ Folder structure

.
├── package.json <-- App dependencies that are installed for the project.
└── index.js <-- The main Node.js script to run the OAuth and API request flow.
└── .env <-- A file you create, where you store sensitive credentials (client ID, client secret).
└── .sample.env <-- A file you can use as the template for your .env file.
└── node_modules <-- Node.js modules that are installed based on dependencies.
└── app-manifest.yaml <-- Yaml code to configure your Miro App. This is used in App Settings -> Manifest.

🫱🏻‍🫲🏽 Contributing

If you want to contribute to this example, or any other Miro Open Source project, please review Miro's contributing guide.

🪪 License

MIT License.