Additional resources

  • API authorization
  • API data service
  • API document
  • API documentation
  • API graph
  • API images
  • API list
  • API visio
  • OAuth 2 documentation

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. If you would like to develop an app that all Lucidchart 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 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

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 `<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 in a browser with the following URL query parameters appended: 


    The client ID you obtained during App registration


    One of the redirect URIs you registered for your app during App registration


    The scopes your app is requesting access to, and currently the only scope is `data-service.admin`

  2. In the browser, Lucidchart 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 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, 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 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.

© 2021 Lucid Software Inc.