Organizations and Authentication

How to authenticate with the Lexamica Integration API and understand your organization's identity.

---

Table of Contents

1. Overview

2. Key Terms

3. How It Works

4. Key Concepts

5. Common Use Cases

6. FAQ

7. Technical Reference

---

🎯 Overview

📌 TL;DR

You have two API keys: a Public Key for sending data to Lexamica, and a Private Key for managing your integration settings. Use the right key for the right task.

Your Organization represents your firm's identity in the Lexamica Integration API. When you're set up as an integration partner, you receive:

• A unique Organization ID that identifies your firm

• A Public Key for sending data into Lexamica (inbound webhooks)

• A Private Key for managing your integration configuration

This two-key system lets you safely expose webhook endpoints to external systems while keeping your administrative operations secure.

---

📖 Key Terms

Term	Definition
Organization	Your firm's account in the Integration API. All your mappings, subscriptions, and keys belong to your organization.
Organization ID	A unique identifier for your organization, used in all API endpoint URLs.
Public Key	An API key designed for inbound webhooks. Can be safely included in URLs or shared with systems that send you data.
Private Key	A secret API key for administrative operations. Must be kept secure and never exposed publicly.
Access Key	A general term for either your Public or Private Key.

---

⚙️ How It Works

The API uses a two-tier authentication model. Each key type grants access to different operations:

Authentication Model
────────────────────

┌─────────────────────────────────────────────────────────────────┐
│                        YOUR SYSTEMS                             │
└───────────────┬─────────────────────────────┬───────────────────┘
                │                             │
                │ Public Key                  │ Private Key
                │ (in URL or Header)          │ (Header only)
                ▼                             ▼
┌───────────────────────────┐   ┌───────────────────────────────┐
│   INBOUND WEBHOOKS        │   │   MANAGEMENT OPERATIONS       │
│                           │   │                               │
│ • Send cases              │   │ • Create/update mappings      │
│ • Accept invitations      │   │ • Manage subscriptions        │
│ • Upload files            │   │ • View logs                   │
│ • Create case updates     │   │ • Rotate access keys          │
└───────────────────────────┘   └───────────────────────────────┘

🎯 Key Takeaway

Use your Public Key when sending data to Lexamica. Use your Private Key when configuring how your integration works.

---

💡 Key Concepts

Public Key Authentication

Your Public Key is designed to be used with inbound webhooks—the endpoints where you send data INTO Lexamica. It can be passed in two ways:

Option 1: Query Parameter

POST /organization/{orgId}/inbound-webhooks/case/{mapId}/send?Key=your_public_key

Option 2: Authorization Header

Authorization: Bearer your_public_key

💡 Tip: The query parameter method is convenient when configuring webhooks in third-party systems that don't support custom headers.

Private Key Authentication

Your Private Key is required for all management operations. It must always be sent in the Authorization header:

Authorization: Bearer your_private_key

⚠️ Warning: Never expose your Private Key in URLs, client-side code, or logs. If compromised, rotate it immediately.

Which Key to Use

Operation	Key Type	Example Endpoints
Send a case to Lexamica	Public	/inbound-webhooks/case/{mapId}/send
Accept/decline invitations	Public	/inbound-webhooks/case-invitation/{mapId}/accept
Upload files	Public	/inbound-webhooks/case/{mapId}/file/upload
Create/update mappings	Private	/mapping/create, /mapping/{mapId}/update
Manage webhook subscriptions	Private	/webhook-subscriptions/create
Manage stored event subscriptions	Private	/stored-event-subscriptions/create
Query stored events	Private	/stored-events
View logs	Private	/logs

---

📋 Common Use Cases

📗 Use Case: Initial Setup

Goal	Get your API credentials and start making requests
How	You'll receive your Organization ID and initial keys when onboarded
Result	You can authenticate with the API

What you'll receive:

{
  "organizationId": "64f1a2b3c4d5e6f7a8b9c0d1",
  "publicKey": "pk_live_abc123...",
  "privateKey": "sk_live_xyz789..."
}

Making your first request:

# Test your Private Key by listing your mappings
curl -X GET \
  "https://integration.lexamica.com/organization/64f1a2b3c4d5e6f7a8b9c0d1/mapping" \
  -H "Authorization: Bearer sk_live_xyz789..."

📗 Use Case: Rotating Keys

Goal	Generate new API keys (e.g., if a key may have been exposed)
How	Call the key creation endpoint with your Private Key
Result	New keys are generated; old keys remain valid until you stop using them

Request:

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/authentication/access-key/create" \
  -H "Authorization: Bearer your_private_key"

Response:

{
  "publicKey": "pk_live_new123...",
  "privateKey": "sk_live_new789..."
}

ℹ️ Note: After rotating keys, update all your integrations to use the new keys, then stop using the old ones.

📕 Use Case: Key Compromised

Goal	Secure your account after a potential key exposure
How	Rotate keys immediately and audit recent activity
Result	New secure keys in place

Step-by-step:

1. Generate new keys using the endpoint above

2. Update all your systems to use the new keys

3. Review your logs for any unauthorized activity

4. Contact support if you see suspicious requests

---

❓ FAQ

❓ "Which key do I use for sending cases?"

🔍 Quick Check:

• ✅ Sending data TO Lexamica? Use Public Key

• ✅ Managing your integration settings? Use Private Key

📝 Full Answer: For any inbound webhook operation (sending cases, accepting invitations, uploading files), use your Public Key. These endpoints are designed to receive data from external systems, and the Public Key can be safely included in webhook configurations.

---

❓ "What happens if I use the wrong key?"

🔍 Quick Check:

• ✅ Getting a 401 Unauthorized error? Check your key type

• ✅ Getting a 403 Forbidden error? You might be using a Public Key for a Private Key operation

📝 Full Answer: If you use your Public Key on a management endpoint (like creating a mapping), you'll receive a 403 Forbidden error. The API validates that the correct key type is used for each operation category.

---

❓ "Can I have multiple key pairs?"

📝 Full Answer: Currently, each organization has one active key pair at a time. When you rotate keys, you receive a new pair. If you need separate keys for different environments (staging vs. production), contact support about setting up multiple organizations.

---

❓ "Where should I store my keys?"

📝 Full Answer:

• Private Key: Store in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.). Never commit to source control.

• Public Key: Can be stored in configuration files or environment variables. While not as sensitive, avoid unnecessary exposure.

---

🔧 Technical Reference

🔧 Technical Deep-Dive: Authentication Headers

All authenticated requests use the Bearer token scheme:

Authorization: Bearer <your_key>

For inbound webhooks only, the Public Key can alternatively be passed as a query parameter:

?Key=<your_public_key>

The API checks authentication in this order:

1. Authorization header (preferred)

2. Query parameter (inbound webhooks only)

Base URLs

Environment	URL
Production	https://integration.lexamica.com
Sandbox	https://integration-demo.lexamica.com

Use the sandbox environment for development and testing before going live.

Error Responses

Status Code	Meaning
401 Unauthorized	Missing or invalid API key
403 Forbidden	Key doesn't have permission for this operation
404 Not Found	Organization ID not found

Example error response:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

---

Last updated: January 2026