Authentication

Loyva uses two authentication mechanisms for API access.

"Partner" in this documentation just means whoever is calling the API — that includes integration partners (like WeSuite) building on Loyva for their own customers, and any Loyva customer org calling the API directly for itself (e.g. to look up its own customers or automate document workflows). Both use the exact same key mechanism, scoped to whichever org created the key.

Partner API keys

API keys are the primary authentication method for server-to-server requests. Any org admin can self-serve create, rotate, or revoke a key scoped to their own org — see Getting a key below.

Format

lk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

All keys are prefixed with lk_ followed by 40 hexadecimal characters.

Usage

Pass the key in the X-API-Key header:

curl https://api.stg.loyva.net/api/v2/partner/envelopes \
  -H "X-API-Key: lk_your_api_key_here"

The organization is derived from the key — no additional org header is required.

Security

• Keys are stored as SHA-256 hashes — Loyva never retains your raw key
• The raw key is shown once at provisioning time. Store it in your secrets manager immediately.
• Keys are scoped to specific permissions (see Scopes)
• Each key has a rate_limit_rpm ceiling (requests per minute)

Getting a key

Any admin in your org can self-serve create a key from Settings → API Keys in the Loyva console, or via the API Keys management API — no Loyva involvement required. See API Keys for the full lifecycle (create, rotate, update scopes, deactivate).

---

Embed tokens

Embed tokens are short-lived JWTs that authorize iframe widgets. They're scoped to a single envelope and widget type, and are safe to hand to the browser.

How it works

Partner Backend                  Loyva API                    User's Browser
      │                              │                              │
      │  POST /embed/token           │                              │
      │  X-API-Key: lk_...           │                              │
      │  { envelope_id, user_email,  │                              │
      │    widget_type: "sign" }     │                              │
      │─────────────────────────────>│                              │
      │                              │                              │
      │  { data: { token, embed_url, │                              │
      │    expires_at, widget_type,  │                              │
      │    envelope_id } }           │                              │
      │<─────────────────────────────│                              │
      │                              │                              │
      │  Return embed_url to frontend│                              │
      │─────────────────────────────────────────────────────────────>│
      │                              │          Loyva.sign({ token })│
      │                              │<─────────────────────────────│
      │                              │    Verify token, serve widget │
      │                              │─────────────────────────────>│

Token properties

Property	Value
Algorithm	HMAC-SHA256
TTL	15 minutes (900 seconds)
Scope	Single envelope + widget type
Audience	embed.stg.loyva.net

Token payload

{
  "envelopeId": "env_x7k9m2p4q1w3",
  "orgId": "org_abc123",
  "userEmail": "signer@example.com",
  "widgetType": "sign",
  "iat": 1712836800,
  "exp": 1712837700
}

Requesting a token

curl -X POST https://api.stg.loyva.net/api/v2/embed/token \
  -H "X-API-Key: lk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "envelope_id": "env_x7k9m2p4q1w3",
    "user_email": "signer@example.com",
    "widget_type": "sign"
  }'

Response (all fields nested under data):

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_at": "2026-04-11T10:15:00.000Z",
    "embed_url": "https://embed.stg.loyva.net/sign/env_x7k9m2p4q1w3#token=eyJ...",
    "widget_type": "sign",
    "envelope_id": "env_x7k9m2p4q1w3"
  }
}

tip

Always request embed tokens from your backend — never expose your API key to the browser. The token is safe to pass to the frontend since it's short-lived and scoped.

---

Authentication summary

Method	Who uses it	Where to send	TTL
API key (lk_...)	Any org's backend — integration partners or direct customers	X-API-Key header	Until deactivated
Embed token	Browser iframes	URL hash fragment	15 minutes