Lystsign API vv1

Authentication

Every call sends Authorization: Bearer <credential> from your server. Requests carrying an Origin header are refused, so browser apps must call through their own backend.

API keys (ls_live_…, or ls_test_… for test mode) are for your own workspace. Create them under Admin → Developers; a key acts as the member who created it.

OAuth 2.0 is for partner apps acting for another workspace. Register the app under Admin → Developers → OAuth apps (confidential apps get a client secret; public apps such as CLIs and native apps use PKCE alone), then run the authorization code flow:

1. Send the user to GET /api/v1/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&scope=…&state=…&code_challenge=…&code_challenge_method=S256. The redirect URI must exactly match a registered one. PKCE (S256) is required for public clients and recommended for all.
2. The user signs in, picks a workspace where they are an owner, admin or developer, and approves. We redirect to your URI with code and your state, or with error=access_denied. Codes are single-use and expire after 2 minutes.
3. POST /api/v1/oauth/token (form-encoded) with grant_type=authorization_code, code, redirect_uri and code_verifier. Authenticate with HTTP Basic (client_secret_basic) or client_id/client_secret in the body; public clients send only client_id.
4. You get an access token (lso_at_…, 1 hour) and a refresh token (lso_rt_…, 30 days). Refresh with grant_type=refresh_token; every refresh returns a new refresh token, and replaying an old one revokes all tokens from that authorization. A refresh may narrow scope but never widen it.
5. Revoke with POST /api/v1/oauth/revoke (RFC 7009, token=…). Revoking a refresh token revokes its access tokens too. Workspace admins can disconnect an app at any time under Developers → Connected apps; its tokens stop working immediately.

An OAuth token acts as the member who approved it, within the granted scopes, and counts against the workspace's plan limits and rate limits. Changes made through it are recorded in the audit log with the app's name. Errors follow RFC 6749 (invalid_grant, invalid_client, …).

Scopes

• envelopes:read: See envelopes, their status, recipients and signed documents
• envelopes:write: Create, send and void envelopes
• templates:read: See templates
• webhooks:manage: Create and change webhook endpoints
• usage:read: See plan usage and limits

Test mode

Create a test key (ls_test_…) under Admin → Developers to build against Lystsign without sending real, binding documents. Everything a test key creates carries livemode: false, and so does every API response and webhook event about it.

• Isolation. Test and live data never mix. A live key gets a 404 for a test envelope and the reverse. Test envelopes are left out of console lists, reports, usage and workspace exports unless you turn on “View test data”.
• Free and bounded. Test envelopes use none of your plan's allowance and are never metered. Test keys have their own limits: 100 API requests per minute, 20 sends per minute and 200 sends per day (UTC).GET /usage reports them under test_mode.
• Email. Test envelopes only email recipients who are verified members of your workspace. Mail to anyone else is captured in the console's Test outbox, with the signing link, and never sent.
• Not binding. The sealed PDF and the certificate of completion carry the watermark “TEST — NOT LEGALLY BINDING”, and the certificate says it was made in test mode. A test envelope can never be converted to a live one; create a new envelope with a live key instead.
• Webhooks. An endpoint created with a test key (or marked Test in the console) is a test endpoint. Test endpoints receive only test-mode events and live endpoints only live events.
• Retention. Test envelopes, their files and their outbox entries are deleted automatically 30 days after they were created.

OAuth access tokens always act in live mode for now.