> For the complete documentation index, see [llms.txt](https://integrate.lexamica.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://integrate.lexamica.com/1.-organizations-and-authentication.md).

# Organizations and Authentication

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

***

## Table of Contents

1. [Overview](#-overview)
2. [Key Terms](#-key-terms)
3. [How It Works](#️-how-it-works)
4. [Key Concepts](#-key-concepts)
5. [Common Use Cases](#-common-use-cases)
6. [FAQ](#-faq)
7. [Technical Reference](#-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:**

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

**Making your first request:**

```bash
# 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:**

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

**Response:**

```json
{
  "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:**

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

***

*Last updated: January 2026*