Authentication
Learn about Mural's OAuth 2.0 authentication flow.
The Mural API uses OAuth 2.0 as a secure method of authorizing interaction between your app and the Mural API. OAuth 2.0 requires that any app's access token request goes through an authentication process with the OAuth provider for extra security. Our current implementation of OAuth 2.0 uses the Authorization Code Grant method.
Also, we support PKCE (Proof Key for Code Exchange) to prevent malicious third parties from attempting to steal your access token.
To see OAuth in use, download the sample app for OAuth flow.
How OAuth 2.0 works
For the Mural API, here’s how the OAuth 2.0 process works for a new user:
- When a user accesses your app, you need to redirect them to
app.mural.co
, the OAuth 2.0 provider. (This approach varies by implementation, but is often a redirect link.) - The user authenticates and authorizes your app at
app.mural.co
, and gets redirected back to your app with an authorization code. - Next, you’ll request an access token for the user with that authorization code.
Once a user is authenticated, here’s how the process works:
- Your app checks to see if there’s a valid access token.
- When the access token expires, you’ll use the refresh token to request a new access token by making a
POST
request to the Refresh Token URL. - The Refresh Token URL responds with a new access token and new refresh token.
To learn more about the specifics of OAuth 2.0, see OAuth 2.0 Authorization Framework.
Set up OAuth 2.0 in Mural
If you’re integrating OAuth 2.0 into an app, you can set up and use an OAuth library in your language of choice. If you simply want to test the API and see how it works, we recommend using Postman or similar.
- To see an example of implementing OAuth using Express (for node.js), go to Basic OAuth Server Setup.
Here are the OAuth endpoints that we’ll reference in the next steps:
- Authorization URL:
https://app.mural.co/api/public/v1/authorization/oauth2/
- Access Token URL:
https://app.mural.co/api/public/v1/authorization/oauth2/token
- Refresh Token URL:
https://app.mural.co/api/public/v1/authorization/oauth2/token
Prerequisites
- Create and log into your Mural account.
- Register your app with Mural. Make sure to save your client ID, client secret, redirect URL(s), and scopes. Each time you request an access token, both the client secret and an authorization request are required. (Always keep your client secret to yourself. Do not share it with anyone.)
Authenticate users: Authorization Request
To authenticate a new user, your app must redirect them to app.mural.co
with specific identifying information. (One common approach is to have a redirect link.) You’ll redirect the user via their browser with a GET
method.
Use this GET
method for a user redirect:
GET https://app.mural.co/api/public/v1/authorization/oauth2/?
client_id=:client_id&
redirect_uri=:callback&
scope=:scope&
state=:state&
response_type=code
Here’s a breakdown of the required parameters in the Authorization Request:
Parameter | Description |
---|---|
client_id | The client identifier for your app. You received this and a client secret when you created your app in Mural. |
redirect_uri | If the user allows access to your app, the auth page will call this URI. Note: This must be one of the values you set as your Redirect URLs when you created your app. |
scope | Mural's scopes have a resource type and a read or write permission. For example, a scope of room:read means the token permits read-only access to room data. Note: The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings. E.g., room:read room:write .To learn more about Mural's scopes, see Scopes. |
state | A value that you randomly generate and store. (This is optional, but recommended.) |
response_type | We currently use the authorization code flow, so the value here is code. |
After the user accesses the above URL, they are taken to Mural’s authentication page. Once they allow access, they are redirected to the Redirect URI specified as the redirect_uri
in the authorization request.
For example, if the provided redirect URI was https://cleverexample.com/oauth/callback
, then here’s how the expected callback request would look: https://cleverexample.com/oauth/callback?code=:code&state=:state
Here’s a breakdown of the parameters in the callback request:
Parameter | Description |
---|---|
code | The authentication code that can be traded for an access token. |
state | If applicable, the state variable that was in the initial URL given to the user. |
Authenticate users: Access Token Request
Next up, the authorization code needs to be passed back to OAuth’s API to get the user’s access token. You make a POST
request:
Request:
POST 'https://app.mural.co/api/public/v1/authorization/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=my_client_id' \
--data-urlencode 'client_secret=my_client_secret' \
--data-urlencode 'redirect_uri=my_callback' \
--data-urlencode 'code=my_code' \
--data-urlencode 'grant_type=authorization_code'
Response:
{
"access_token": <TOKEN>,
"expires_in": <EXPIRATION (in seconds)>,
"refresh_token": <REFRESH TOKEN>
}
Here’s a breakdown of the parameters in the Access Token Request:
Parameter | Description |
---|---|
client_id | The client identifier for your app. You received this and a client secret when you created your app in Mural. |
client_secret | The secret key you copied when you created your app in Mural. |
redirect_uri | Include if you used this parameter in the authorization request. Their values must be identical. |
code | The authorization code received from the authorization server. |
grant_type | The value must be authorization_code . |
If the parameters match, you’ll receive a JSON response with the user access token and token expiration.
Use the OAuth Token
Once you have the user access token, you call the API, passing a Bearer authorization header. Here’s an example of how to use it:
curl -sH 'Authorization: Bearer <ACCESS_TOKEN>'
'https://app.mural.co/api/public/v1/workspaces'
Refresh Token Request
By default, OAuth tokens expire after 15 minutes, so you’ll likely need to refresh your stored tokens. You do this using refresh_token
and the following endpoint: https://app.mural.co/api/public/v1/authorization/oauth2/token
You can reuse your refresh_token
as many times as you need to get a new access_token
. You’ll do a POST
request to refresh the token. Here’s how that looks:
Request:
POST 'https://app.mural.co/api/public/v1/authorization/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=my_client_id' \
--data-urlencode 'client_secret=my_client_secret' \
--data-urlencode 'refresh_token=my_refresh_token' \
--data-urlencode 'grant_type=refresh_token'
Response:
{
"access_token": <TOKEN>,
"expires_in": <EXPIRATION (in seconds)>
}
Here’s a breakdown of the parameters in the Refresh Token Request:
Parameter | Description |
---|---|
client_id | The client identifier for your app. You received this and a client secret when you created your app in Mural. |
client_secret | The secret key you copied when you created your app in Mural. |
refresh_token | The refresh token issued by the authorization server. |
grant_type | The value must be refresh_token . |
Common Authorization Token Request errors
There are several things that can go wrong during the authorization token request step. Here are a few of the more common ones:
Invalid Request
If the request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed, you will receive the following error:
{
"error": "invalid_request",
"error_description": "The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed."
}
Incorrect Client Credentials
If your client credentials are invalid (client_id
or client_secret
), client authentication failed, you will receive the following error:
{
"error": "invalid_client",
"error_description": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method."
}
Redirect URI Mismatch or Invalid Grant
If the provided authorization grant (code) or refresh token is invalid, already used, expired, revoked, does not match the redirect_uri
used in the authorization request, or was issued to another client, you will receive the following error:
{
"error": "invalid_grant",
"error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}
Unsupported Grant Type
If the authorization grant type is not supported by the authorization server, you will receive the following error:
{
"error": "unsupported_grant_type",
"error_description": "The authorization grant type is not supported."
}
Updated over 1 year ago