Obtaining an access token

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

Step 1

Direct the user to the appropriate authorization url in a browser with the following URL query parameters appended in order to grant access:

ParameterDescriptionRequired
client_idThe client ID obtained during App registrationYes
redirect_uriOne of the redirect URIs registered for the app during App registrationYes
scopeThe scopes the app is requesting access toYes
stateCan be any value. Will be included in the redirect back to the app once authorization is completedNo
promptControls whether the grant access page is shown or not. Possible values: none | consent. If none, will try to skip the grant access page, and will fail if a user has not provided consent in the past. If not provided, will first attempt skipping the grant access page, but will open the page if the user has not provided consent before.No (Only available for user token flow)

📘

Login Redirect

If the user has not yet logged into Lucid, the redirect will first take them to a login page, and then display the grant access page.

https://lucid.app/oauth2/authorize
    ?client_id=rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf
    &redirect_uri=https://lucid.app/oauth2/clients/rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf/redirect
    &scope=lucidchart.document.content%20offline_access%20user.profile

Step 2

Once the user grants access, they will be redirected to the URI provided in redirect_uri with a code query parameter. The code parameter contains a short-lived (5 minutes) authorization code that will be used to obtain an access token.

  • If using an API tool like Postman, you can use the Test Redirect Uri to retrieve the code manually while developing your integration.
https://lucid.app/oauth2//clients/rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf/redirect
    ?code=vtpL4oKCv3LSJ8C78FohTYN9uJUUkkZ4mQDYBucl094r

Step 3

Make a POST request to https://api.lucid.co/oauth2/token with a Create Access Token body containing the code provided.

curl 'https://api.lucid.co/oauth2/token' \
     --request 'POST' \
     --header 'Content-Type: application/json' \
     --data-raw '{
         "code": "vtpL4oKCv3LSJ8C78FohTYN9uJUUkkZ4mQDYBucl094r",
         "client_id": "rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf",
         "client_secret": "x678fc0SyuAbyleYq8MMtpxZMD7y4WFpPuf5a",
         "grant_type": "authorization_code",
         "redirect_uri": "https://lucid.app/oauth2/clients/rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf/redirect"
     }'

Step 4

The response will be an OAuth2 Token.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "oauth2-N2QyNWE3NmViMTg4NzAyMTM5ODYzNDAzZWE5NGVhNzQ0OGUzZTc2N...",
    "refresh_token": "oauth2-ZjU3OGVmMmVmZTEzMDI1OWU4M2M2MTI4ZjY2OWEwZDdhODE3NWVjZ...",
    "user_id": 1268,
    "client_id": "rd0q2geEEHcDvZNpYmYAXBH5eCHYD8x0sCwVyncf",
    "expires_in": 3600,
    "expires": 1633107891024,
    "scopes":[
        "lucidchart.document.app",
        "offline_access"
    ],
    "token_type": "bearer"
}