> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luminpdf.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Signing Session
> Returns a short-lived sign_url for embedding the Lumin signing experience with the Embed Signing SDK.
This endpoint requires the following scope:
`sign:requests`
## OpenAPI
````yaml POST /signature_request/{signature_request_id}/signing-session
openapi: 3.1.0
info:
version: 1.0.0
title: Lumin API Reference
description: >
The Lumin API Reference provides a comprehensive set of tools to integrate
document workflows — including editing, eSignatures, and automation — into
your applications.
Useful links:
- [Document Repository](https://github.com/luminpdf/luminsign-docs)
- [API
Definition](https://github.com/luminpdf/luminsign-docs/blob/main/openapi.yaml)
- [Authentication Guide](/tabs/guides/authentication/overview)
termsOfService: https://www.luminpdf.com/terms-of-use/
contact:
name: API Support
email: integration@luminpdf.com
url: https://help.luminpdf.com
servers:
- url: https://api.luminpdf.com/v1
description: Production server
security: []
tags:
- name: Signature Requests
description: Everything about Signature Requests
- name: Users
description: Everything about Users
- name: Templates
description: Everything about Templates
- name: Documents
description: Everything about Documents
- name: Workspaces
description: Everything about Workspaces
- name: Agreements
description: Everything about Agreements
paths:
/signature_request/{signature_request_id}/signing-session:
post:
tags:
- Signature Requests
summary: Create Signing Session
description: >
Returns a short-lived embedded-signing session URL (`sign_url`) for a
single recipient on an existing signature request. Load this URL into
the
[`@luminpdf/lumin-embed-signing-sdk`](https://www.npmjs.com/package/@luminpdf/lumin-embed-signing-sdk?activeTab=readme)
iframe to render the signing experience inline.
Each session is scoped to one `signature_request_id` + `signer_email`
pair. The signature request must have been created via the public API
(`/signature_request/send` or `/signature_request/send-from-template`).
For redirect or hosted signing flows, use [Get Signing
Link](/tabs/api-reference/api/signature-requests/get-signing-link)
instead. See the [Embedded Signing
walkthrough](/tabs/guides/walkthroughs/embedded-signing) for integration
steps and domain verification requirements.
operationId: create-signing-session
parameters:
- in: path
name: signature_request_id
schema:
type: string
required: true
description: >-
ID of an existing signature request that was created via the public
API (`/signature_request/send` or
`/signature_request/send-from-template`).
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- signer_email
properties:
signer_email:
type: string
description: >-
Email address of the recipient this session is being issued
for. Must be a recipient (signer/viewer) already attached to
the signature request.
expiry:
type: integer
description: >
How long the returned `sign_url` remains valid, in
milliseconds from issue time.
**Default:** `900000` (15 minutes)
**Accepted range:** `300000` – `3600000` (5 minutes – 1
hour, inclusive). Shorter values are intended for
security-sensitive host apps.
default: 900000
minimum: 300000
maximum: 3600000
example:
signer_email: signer1@example.com
expiry: 900000
responses:
'200':
description: Embedded-signing session created successfully.
content:
application/json:
schema:
type: object
required:
- sign_url
- signer_email
- expires_at
- status
properties:
sign_url:
type: string
description: >-
Short-lived URL the Embed Signing SDK loads into its
iframe. Includes a single-use session token bound to
`signature_request_id` and `signer_email`.
signer_email:
type: string
description: Echoes the recipient this session was issued for.
expires_at:
type: integer
description: >-
Absolute expiry of `sign_url`. After this time the SDK
will receive an `expire` event and the URL must be
re-issued.
status:
type: string
description: Current signing status of the recipient at issue time.
enum:
- NEED_TO_SIGN
- WAITING_FOR_OTHERS
example:
sign_url: https://sign.luminpdf.com/embed?session=8647b08b...
signer_email: signer1@example.com
expires_at: 1927510980694
status: NEED_TO_SIGN
4XX:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKey: []
- BearerAuth:
- sign:requests
components:
schemas:
Error:
type: object
required:
- error_code
- error_message
properties:
error_code:
type: string
description: The system error code.
error_message:
type: string
description: The human-readable error message.
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-API-Key
description: >
Provide your API key in the `X-API-Key` header, e.g., `X-API-Key:
YOUR_API_KEY`.
BearerAuth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.luminpdf.com/oauth2/auth
tokenUrl: https://auth.luminpdf.com/oauth2/token
scopes:
openid: >-
Retrieve basic identity details (username, email, profile
picture).
offline_access: Request a refresh token for long-lived access. Private apps only.
profile.read: View basic user profile information.
workspaces: View and manage Workspaces and Spaces.
workspaces.read: View information about the authenticated user's Workspace.
templates: View and manage templates in a Workspace.
pdf:files: Create, edit, and delete PDF files in a Workspace.
pdf:files.read: Retrieve PDF documents stored in a Workspace.
sign:requests: Create, update, or view signature requests.
sign:requests.read: Retrieve signature requests.
agreements: Create, update, or delete AgreementGen documents.
description: >
OAuth 2.0 authorization code flow. Provide your access token in the
`Authorization` header, e.g., `Authorization: Bearer `. See the
[OAuth 2.0 guide](/tabs/guides/authentication/oauth2) for details.
````