Learn how to create API keys, use them in requests, and troubleshoot auth errors.

Authentication

Every request to the Leypal REST API must be authenticated. Leypal uses API keys — long-lived secrets you generate from the Dashboard and include in each request via the x-api-key header.

What is an API Key?

An API key is a unique secret token that identifies your application to the Leypal API. Think of it as a password for your integration: it tells Leypal which organization is making the request and what actions are permitted.

Key characteristics:

Machine-to-machine authentication — no user login required at runtime
Unique per organization — each organization has a single API key
Revocable — can be deleted and regenerated at any time
Never expires (unless you revoke it manually)

Single prefix format:

All keys follow the format sk_ followed by alphanumeric characters. There is no distinction between test and production keys — your system administrator will provide you with a dedicated test organization account if needed.

Generating Your API Key

Follow these steps to create a new API key from the Leypal Dashboard:

Log in to your Leypal Dashboard at app.leypal.com
Navigate to Advanced → API & Webhooks
Click Generate API Key
Copy the key immediately — it is displayed only once and cannot be retrieved later
Store it securely (see Security Best Practices)

Important: If you lose your key, you cannot recover it. You must revoke the old key and generate a new one.

Using Your API Key in Requests

Include your API key in the x-api-key header of every request:

x-api-key: YOUR_API_KEY

curl Example

curl -X GET https://api.leypal.com/api/v1/signatures \
  -H "x-api-key: sk_abc123xyz..."

Create a Signature Request

curl -X POST https://api.leypal.com/api/v1/signatures \
  -H "x-api-key: sk_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "advanced",
    "originalDocumentName": "Service Agreement.docx",
    "originalDocumentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "originalDocumentExtension": "docx"
  }'

Retrieve a Signature Request

curl -X GET https://api.leypal.com/api/v1/signatures/1042 \
  -H "x-api-key: sk_abc123xyz..."

Key Security Best Practices

Treat your API key like a password. A leaked key gives attackers full access to your Leypal account within the granted scopes.

Never commit keys to version control. Use environment variables or a secrets manager instead.
```
# .env (gitignored)
LEYPAL_API_KEY=sk_abc123xyz...
```
Never expose keys in client-side code. All API calls must go through your backend server.
Rotate keys every 90 days. Go to Advanced → API & Webhooks → select a key → click Rotate.
Revoke immediately if compromised. Advanced → API & Webhooks → select a key → click Revoke.
Store in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler).

Error Codes & Remediation

401 Unauthorized

The request was rejected because the API key is missing, invalid, or expired.

Cause	Symptom	Fix
Missing `x-api-key` header	`"message": "Unauthorized"`	Add `-H "x-api-key: YOUR_KEY"` to the request
Invalid key format	`"message": "Invalid API key format"`	Ensure the key starts with `sk_`
Key was revoked	`"message": "API key revoked"`	Generate a new key in Advanced → API & Webhooks
Typo in key value	`"message": "Unauthorized"`	Re-copy the key from the Dashboard (exact match required)

Example 401 response:

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

429 Too Many Requests

Your integration has exceeded the API rate limit: 1,000 requests per minute.

Cause	Fix
Burst of rapid requests	Wait 60 seconds before retrying
Polling too frequently	Use webhooks instead of polling — they deliver events in real time
No request queuing	Add a queue with rate limiting in your integration layer

Example 429 response:

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests",
  "error": "Too Many Requests"
}

Response headers on 429:

Retry-After-App: 60

Troubleshooting FAQs

Q: I lost my API key. How do I recover it?

You cannot recover a key after it is created — Leypal only shows it once. Go to Advanced → API & Webhooks, revoke the lost key, and generate a new one. Update all systems using the old key.

Q: How many API keys can I have?

Each organization has a single API key. If you need a different key, you will need to create a new organization or contact your system administrator.

Q: How often should I rotate API keys?

Rotate keys every 90 days as a baseline. Rotate immediately if:

A key is accidentally committed to a repository
A team member with access to the key leaves
You suspect the key has been exposed

Q: Can I restrict a key to specific IP addresses?

No. There is currently no ability to restrict an API key to specific IP addresses. The key is valid from any location.

Q: My request returns 401 but I am sending the header. What else could cause this?

Common pitfalls:

Extra whitespace in the key value — ensure no leading or trailing spaces
Encoding issues — the key must be sent as plain ASCII, not URL-encoded

Authentication

On this page