OAuth 2 Documentation


OAuth 2.0 Limitations

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

  • You must be a team admin in your Lucidchart 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. There is currently no way to use OAuth 2.0 to develop an app that all Lucidchart users can use.
  • Authorization cannot happen through Postman because a user must give consent for the client to access their information.

OAuth 2.0 Authorization

In order to use any of the Lucidchart 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. Lucidchart will redirect the user to this location once they have granted access. This should be a URL that you control. Lucidchart will append the authorization code to the URL in the code query parameter.

Note: As a service, Lucidchart 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://www.lucidchart.com/oauth2/clients/<your client id>/redirect`. When you use this redirect URI and a user grants access to your app, Lucidchart 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 Lucidchart account, use the following flow:

  1. Direct the user to open  https://www.lucidchart.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://www.lucidchart.com/oauth2/authorize?client_id=rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf&redirect_uri=https://www.lucidchart.com/oauth2/clients/rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf/redirect&scope=data-service.admin
  2. 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.
  3. Make a POST request to https://users.lucidchart.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"
    }
  4. The response will have a JSON object body. It will contain access_token, refresh_token, and expires properties, 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 Lucidchart 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 Lucidchart 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.lucidchart.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, and expires properties, which hold the access token, the refresh token, and the expiration time (in milliseconds since 1 Jan 1970) respectively.

Note: Refreshing a token invalidates the old access and refresh tokens. Be sure your app stores the new tokens returned in the response described above.