Register your app
Once you've built your app, register it so that it can interact with MURAL!
This article introduces you to My apps in your MURAL Account Settings, where you can register and update apps that use the MURAL API ᴮᴱᵀᴬ.
My apps is a section of your MURAL profile that enables you to build integrations or create apps that use the MURAL API ᴮᴱᵀᴬ.
Here's how to get to My apps:
-
In the bottom left corner, click your avatar, then click My apps.
In My apps, you can create new apps, and update or delete existing apps.
If you don't yet have a MURAL account, you can sign up for free here: https://app.mural.co/signup."
Create and register a new app
Third-party developers with a MURAL account can create their own applications that use MURAL's API. By creating an app in My apps, you're registering your app with MURAL so that it can interact with our platform.
By registering your app in My apps, you are declaring a statement of intent between your app and MURAL. It's a sort of manifest saying, "Here's my application, and here is how it should integrate with MURAL."
Here's how to register your app:
-
In the bottom left corner, click your avatar, then click My apps.
-
In My apps, click the New app button.
-
Fill out the following information. See App Properties below for details.
- App Name
- App Description
- Logo URL
- Documentaion
- Homepage URL
- Redirect URLs*
- Reject URL
- Allowlist Domains
For testing with Postman, you must add https://oauth.pstmn.io/v1/callback as one of the Redirect URLs.
-
Select the Permission scopes required for the app. Read more information on scopes.
-
Click the Create button to register your app. The Edit app screen is displayed with your new Client ID and Client Secret.
-
On the Edit app screen, copy the Client ID and Client Secret for the app and store them in a safe location.
-
In the top right, click the Back to Apps link to return to the Apps screen.
For security reasons, we do not store the Client Secret for your app. You will not be able to view the Client Secret once leaving this screen.
If you have forgotten your Client Secret, you can reset it by editing your app.
Now that you have registered your app with MURAL and have a Client ID and Client Secret, you can start creating your app with your favorite development tool.
App credentials
Client ID
A unique ID for your app. It is generated by MURAL when you first register your app. After that, it cannot be changed, but is displayed at the top of My apps. You may choose to share it publicly. The Client ID is required to authenticate with OAuth 2.0.
Example
d1c72afc39d2-4218-7ef4-6e56-cd4c8e04
Client Secret
A unique authentication string for your app. It is generated by MURAL, and is only displayed when you first register or reset your app.
Treat your Client Secret as a password. Do not share it publicly. The Client Secret is required to authenticate with OAuth 2.0.
Example
a3164fc953794514235b0b2dacbdd8c2f8f0f1623f5826abdba779c379ed0bdbbaa9f6faec61cb5c0f8a3545ed4cdf43ec08a659c3ee0aa6e5af114a6e889918
If you have forgotten your Client Secret, you can reset it by editing your app.
App properties
App name
The name of the app. The App Name appears in the following locations:
- Your company's integrations (admins only)
- User integrations
- On the MURAL user consent screen and within error messaging
Example
My Awesome App
App description
The description of the app. This text appears in My apps, so that you may describe the app's intended function.
Example
My Awesome App does a, b, and c. It does not do x, y or z.
Logo URL
The URL of an image, used as the app logo. It is displayed on My apps, and the consent screen. If the URL is not valid, a warning icon is displayed in place of the image in My apps.
Example
https://myawesomeapp.com/logo.png
Documentation (Optional)
The URL of your app's documentation. It is displayed on My apps, and the user integrations screen.
Example
https://myawesomeapp.com/docs/
Homepage URL
The URL of the homepage for the app. This is a reliable link used to take users to the app homepage. It is used when:
- The user clicks the app logo on the consent screen.
- The user clicks the "Go Back to {clientName}" button at the bottom of error message screens, such as if OAuth fails.
Example
https://myawesomeapp.com
Redirect URLs
An allowlist of all redirect URLs accepted for completing the OAuth flow. If the redirect URL is not in this list, the Error Message text is displayed when initializing the OAuth flow.
If you're testing the API through Postman, a common redirect URL is https://oauth.pstmn.io/v1/callback
.
Examples
https://myawesomeapp.com/oauth2/callback
https://testing.myawesomeapp.com/oauth/callback
Reject URL (Optional)
The URL of a page to display for the following errors:
- The requested scopes are empty. This indicates an issue with OAuth flow.
- The company that the user belongs to does not allow this application for their users. This indicates a configuration issue on the company side.
The single Reject URL is used for all error types listed above. If not defined, the default "Uh-oh page" is used.
Example
https://myawesomeapp.com/oops
Allowlist domains (Optional)
An allowlist of CORS domains. You may use an asterisk (*) as a wildcard for part of a domain.
Examples
google.com
*.ngrok.io
Permission scopes
An allowlist of scopes that the app may access. If the app attempts to access scopes outside this allowlist (during OAuth flow initialization), the default "Uh-oh page" is displayed.
Changing an app's permission scopes after an app is installed can affect the user experience. See Making changes to scopes for more information.
Examples
rooms:read
workspaces:read
murals:write
Change existing app settings
You may change the settings for apps you have created in My apps.
Here's how to change your app settings:
-
In the bottom left corner, click your avatar, then click My apps.
-
Click an app to edit it.
-
Update the App info.
-
Click the Save changes button.
Delete an app
Deleting an app from My apps removes the app from your MURAL account, and disables access to the API for the app using that Client ID and Client Secret.
If a user has installed your app, deleting it can affect the user experience. A user who has installed your app and has been granted an access token may continue to interact with the API until that token expires. Access tokens expire every 15 minutes.
Deleting an app is immediate and permanent. Use with caution.
To delete an app from My apps:
-
In the bottom left corner, click your avatar, then click My apps.
-
Click an app to edit it.
-
Click the Delete app button. A warning is displayed.
-
If you're certain you wish to delete your app, click the Delete button.
Updated about 5 hours ago