OAuth 2

OAuth 2.0 Limitations

When accessing Marq APIs using OAuth 2.0, the following limitations apply:

• You must be a team admin in your Marq account in order to obtain the client ID and secret as described below.
• Only users in your account can use the app with your client ID and secret. If you would like to develop an app that all Marq users can use, please contact us.
• Authorization must happen in the browser, because a user must give consent for the client to access their information. For this reason, the authorization request cannot be made from Postman, curl, or some other HTTP client.

OAuth 2.0 Authorization

In order to use any of the Marq APIs, an app must have permission from the user to access their data. This permission can be granted with an OAuth access token following the OAuth 2.0 specification. Details of the OAuth 2.0 authorization process can be found at https://oauth.net/2/.

App registration

To set up your app to use OAuth 2.0, you will need to perform the following steps:

• Obtain an OAuth 2.0 client ID and client secret from this page.
• Register at least one redirect URI on that page. Marq will redirect the user to this location once they have granted access. This should be a URL that you control. Marq will append the authorization code to the URL in the `code` query parameter.

Note: As a service, Marq provides a redirect uri for you to use that allows the user to copy the authorization code to the clipboard. To use it, register the redirect URI `https://app.Marq.com/oauth2/clients/<your client id>/redirect`. When you use this redirect URI and a user grants access to your app, Marq will redirect the user to a page on our site where they can view and copy the authorization code.

Authorization (obtaining an access token)

When a user wants to allow your app to connect to their Marq account, use the following flow:

1. Direct the user to open  https://app.Marq.com/oauth2/authorize in a browser with the following URL query parameters appended: 

   client_id	The client ID you obtained during App registration
   redirect_uri	One of the redirect URIs you registered for your app during App registration
   scope	The scopes your app is requesting access to, and currently the only scope is `data-service.admin`

   Example: https://app.Marq.com/oauth2/authorize?client_id=rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf&redirect_uri=https://app.Marq.com/oauth2/clients/rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf/redirect&scope=data-service.admin

2. In the browser, Marq prompts the user to log in and then asks them to grant access to your app.
3. Once the user grants access, they will be redirected to the URI you specified. The `code` query parameter will contain a short-lived authorization code that you will use to obtain an access token.
4. Make a POST request to
   

   https://users.app.Marq.com/oauth2/token

   with the following parameters in a JSON object in the body:

    {
   
    "code": "<the authorization code>",
   
    "client_id": "<your client ID>",
   
    "client_secret": "<your client secret>",
   
    "grant_type": "authorization_code"
   
    }

5. The response will have a JSON object body. It will contain

   access_token

   refresh_token

   expiresproperties

   which hold the access token, the refresh token, and the expiration time (in milliseconds since 1 Jan 1970) respectively.

Using the access token

With the access token, your app can make requests to Marq APIs and get access to the user's data. Note: Access can be revoked by the user or team admin at any time if they decide that they no longer want your app to have access to the user's Marq data.

To make an authenticated request, include an authorization header with your access token as a "Bearer" token. The header value should look like this:

Bearer <your access token>

Refreshing the access token

All access tokens have a brief usable lifetime (currently one hour), after which they expire. To continue accessing that user's data, your app should obtain a new token using the refresh token that was issued alongside the access token. This refresh must be performed before the token's expiration time is reached.

To refresh a token, make a POST request to https://users.app.Marq.com/oauth2/refreshToken with a JSON body that looks like this:

{
 "refresh_token": "<the refresh token>",
 "client_id": "<your client ID>",
 "client_secret": "<your client secret>",
 "grant_type": "refresh_token"
 }

The response will match the format of the authorization response. It will contain

access_token

refresh_token

expiresproperties

which hold the access token, the refresh token, and the expiration time (in milliseconds since 1 Jan 1970) respectively.