OAuth 2.0 - Lumin Developer Docs

OAuth 2.0 lets your application request access to a user’s Lumin account on their behalf. The user reviews the requested permissions on a consent screen and explicitly approves or denies access. This makes OAuth 2.0 the right choice when your application acts on behalf of individual Lumin users rather than a single shared workspace. Lumin supports the authorization code flow with two client types:

Client type	Use case	Client secret required	Refresh tokens
Public (PKCE)	Mobile apps, SPAs, desktop apps	No — uses PKCE instead	No
Private/Server	Server-side web apps, backend services	Yes	Yes

Public (PKCE) apps do not receive refresh tokens. When the access token expires, the user must re-authorize. If your app needs long-lived background access, create a Private/Server app instead.

Register your application

Before you can use OAuth 2.0, register your application in Lumin. You must be a Workspace Owner to do this. Each Workspace can have up to 5 integration apps.

Open Integration apps

Set application details

Enter an Application name and select an Application type:

Public Application — no client secret, uses PKCE. Choose this for mobile apps, SPAs, or desktop apps.
Private Application — server-based with a client secret. Choose this for backend or server-side applications.

You cannot change the application type after creation. If you need a different type, create a new application.

Select scopes

Choose only the scopes your application actually needs. The scopes you select appear on the user consent screen. See Scopes for the full list.

Configure redirect URIs

Enter one or more redirect URIs where Lumin will send users after they authorize your app.

Must use https:// or an app-specific scheme (e.g., myapp://callback)
No wildcards, IP addresses, or relative paths
Separate multiple URIs with commas

Configure consent screen

Fill in the information users will see when granting access: app logo, website URL, Privacy Policy URL, Terms of Use URL, and a contact email.

Save and retrieve credentials

Click Create. You will receive:

Client ID — required for all OAuth 2.0 flows
Client Secret — issued only for Private Applications

Store these credentials securely. Do not hardcode them in your source code or commit them to repositories.

Authorization code flow

Private / Server app
Public app (PKCE)

Use this flow for server-side applications. The flow uses a client secret and issues refresh tokens so your server can maintain access without user re-interaction.

Redirect the user to the authorization endpoint

Send the user to Lumin’s authorization URL with your app’s parameters:

GET https://auth.luminpdf.com/oauth2/auth
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=openid offline_access sign:requests
  &state=RANDOM_STATE_VALUE
  &nonce=RANDOM_NONCE_VALUE

Include offline_access in the scope to receive a refresh token.After the user approves access, Lumin redirects them to your redirect_uri with an authorization code in the query string.

Exchange the authorization code for tokens

Make a server-to-server POST request to exchange the code for an access token and refresh token:

curl -X POST "https://auth.luminpdf.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=YOUR_AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

Lumin returns the tokens:

{
  "access_token": "eyJhbGci0i...",
  "expires_in": 3600,
  "refresh_token": "def502...",
  "token_type": "bearer",
  "scope": "openid offline_access sign:requests"
}

Call Lumin APIs with the access token

Pass the access token in the Authorization header as a Bearer token:

curl -X GET "https://api.luminpdf.com/v1/user/info" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Refresh the access token

Access tokens expire after 1 hour. Use the refresh token to get a new access token without requiring the user to re-authorize:

curl -X POST "https://auth.luminpdf.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Use this flow for mobile apps, SPAs, and desktop apps that cannot securely store a client secret. PKCE (Proof Key for Code Exchange) replaces the client secret with a cryptographic challenge. Lumin supports the S256 (SHA-256) PKCE method.

Generate a PKCE code verifier and challenge

Create a code_verifier: a cryptographically random string.
Generate a code_challenge by hashing the code_verifier with SHA-256 and encoding the result as Base64URL.
Use code_challenge_method=S256.

code_verifier  = "R8zFoqsOyeysd881QITZs3dK1YsdIvFNBf04D1bukBw"
code_challenge = "RqN6kvc2f99WD-BQG3SzsDfQcX54BxuyuM40alAt8b5M"

Store the code_verifier — you will need it in step 3.

Redirect the user to the authorization endpoint

Send the user to Lumin’s authorization URL, including the PKCE parameters:

GET https://auth.luminpdf.com/oauth2/auth
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=openid sign:requests
  &state=RANDOM_STATE_VALUE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256

After the user approves, Lumin redirects them to your redirect_uri with an authorization code.

Exchange the authorization code for an access token

Exchange the code for an access token. Provide the code_verifier instead of a client secret:

curl -X POST "https://auth.luminpdf.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=YOUR_AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

{
  "access_token": "ory_at__aqzPqv1z0Uw...",
  "expires_in": 3598,
  "token_type": "bearer",
  "scope": "openid sign:requests"
}

Public apps do not receive a refresh_token. When the access token expires, start a new authorization flow.

Call Lumin APIs with the access token

Pass the access token in the Authorization header:

curl -X GET "https://api.luminpdf.com/v1/user/info" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Scopes

Scopes define what your application can access. Request only the scopes your app actually needs — users see the requested scopes on the consent screen.

Category	Scope	Description
Account	`openid`	Retrieve basic identity details (username, email, profile picture).
Account	`offline_access`	Request a refresh token for long-lived access. Private apps only.
Account	`profile.read`	View basic user profile information.
Account	`profile.settings`	Manage user account settings.
Workspace	`workspaces`	View and manage Workspaces and Spaces.
Workspace	`workspaces.read`	View information about the authenticated user’s Workspace.
Templates	`templates`	View and manage templates in a Workspace.
Documents	`pdf:files`	Create, edit, and delete PDF files in a Workspace.
Documents	`pdf:files.read`	Retrieve PDF documents stored in a Workspace.
Signature Requests	`sign:requests`	Create, update, or view signature requests.
Signature Requests	`sign:requests.read`	Retrieve signature requests.
Agreements	`agreements`	Create, update, or delete AgreementGen documents.

Private integration apps receive the openid and offline_access scopes by default.

You can view the scope string for an existing application by opening its Application details modal in Settings → Developer settings → Integration apps.

​Register your application

​Authorization code flow

​Scopes

Register your application

Authorization code flow

Scopes