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:

Log into MURAL.
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:

Log into MURAL.
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:

Log into MURAL.
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:

Log into MURAL.
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.