Authentication

Loyva uses two authentication mechanisms for partner integrations.

Partner API keys

API keys are the primary authentication method for partners. They authenticate server-to-server requests.

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

Loyva provisions partner keys during onboarding — see API Keys. Rotations, scope changes, and deactivations are also handled by your Loyva point of contact.

---

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": "[email protected]",
  "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": "[email protected]",
    "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_...)	Partner backends	X-API-Key header	Until deactivated
Embed token	Browser iframes	URL hash fragment	15 minutes