> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edges.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand Identities, Integrations, and how Edges connects to LinkedIn.

<Info>
  **TL;DR:** Edges uses **Identities** (your users) connected to **Integrations** (LinkedIn accounts) to run **Actions**. That's it.
</Info>

## How Edges Works

```
Your App  →  Identity  →  Integration (LinkedIn)  →  Action  →  Results
```

| Entity               | What it is                   | Example                         |
| -------------------- | ---------------------------- | ------------------------------- |
| **Workspace Member** | Someone who logs into Edges  | Your team, admins               |
| **Identity**         | An end user in *your* app    | Your customer's account         |
| **Integration**      | A connected platform account | A LinkedIn profile              |
| **Action**           | An operation you execute     | "Search People", "Send Message" |

***

## Identities vs. Workspace Members

Edges distinguishes between two types of users:

|                | Workspace Member                                                  | Identity                                    |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------- |
| **Who**        | Your team                                                         | Your end users                              |
| **Access**     | Edges dashboard                                                   | None (API only)                             |
| **Purpose**    | Manage settings, billing                                          | Execute automated actions                   |
| **Example**    | Admin, developer, ops                                             | LinkedIn account for outreach               |
| **How to add** | [Invite via Members page](https://app.edges.run/settings/members) | [Create via API](/v1/api/identities/create) |

### Workspace Member Roles

| Role      | Permissions                                             |
| --------- | ------------------------------------------------------- |
| **Admin** | Full access: Members, Identities, Integrations, Billing |
| **Ops**   | Manage Identities & Integrations (no billing)           |
| **User**  | Read-only access                                        |

### What is an Identity?

An **Identity** represents an end user in your SaaS or AI agent platform. Identities:

* Execute automated Actions on your behalf
* Connect to Integrations (like LinkedIn)
* Have no access to the Edges dashboard
* Are ideal for mapping your users to integration accounts

<Note>
  **When do you need Identities?** Only for actions that require being "logged in" — sending messages, accepting invitations, etc. For generic enrichment, use [Managed Mode](/v1/identities/modes#managed-mode) instead.
</Note>

### Identity Modes

Control how accounts execute your Actions:

| Mode      | Setup            | Cost         | Best for                 |
| --------- | ---------------- | ------------ | ------------------------ |
| `managed` | None             | 1.5× credits | Getting started, testing |
| `direct`  | Connect accounts | Standard     | User-specific outreach   |
| `auto`    | Rent accounts    | \$70-125/mo  | High-volume operations   |

<Tip>
  See the [Quickstart](/v1/quickstart#identity-modes-explained) for code examples of each mode.
</Tip>

### Managing Identities

<Steps>
  <Step title="Create an Identity">
    Use the [Create Identity API](/v1/api/identities/create) or the [Identities page](https://app.edges.run/identities).
  </Step>

  <Step title="Connect an Integration">
    Link a LinkedIn account via [Chrome Extension](/v1/linkedin/chrome-extension), [API authentication](/v1/api/linkedin/authentication), or [cookies](/v1/api/integrations/connect).
  </Step>

  <Step title="Execute Actions">
    Use `identity_ids` in your API calls to specify which Identity runs the Action.
  </Step>
</Steps>

<Note>
  **Licensing:** Identity seats are included in your plan. Check [Pricing](https://edges.run/pricing) for your allocation. Contact [sales@edges.run](mailto:sales@edges.run) for higher limits.
</Note>

### Identity Security

Every Identity is assigned a unique IP address for enhanced security. Learn more about [Identity management and security](/v1/identities/add-manage-identities).

***

## Integrations

An **Integration** connects an Identity to an external service (LinkedIn, Sales Navigator, etc.).

* Each Integration belongs to **one Identity**
* Integrations authenticate your requests with third-party APIs
* Multiple Integrations can connect to the same Identity (e.g., LinkedIn + Sales Navigator)

### LinkedIn Integrations

| Feature                | Description                                            |
| ---------------------- | ------------------------------------------------------ |
| **Smart Limits**       | Edges auto-enforces safe usage to prevent restrictions |
| **Supported Licenses** | Sales Navigator, Premium, Recruiter Lite               |
| **Account Rental**     | Skip the hassle of warming up accounts                 |

<CardGroup cols={2}>
  <Card title="Smart Limits" icon="shield" href="/v1/linkedin/limits">
    How Edges protects your accounts
  </Card>

  <Card title="LinkedIn Licenses" icon="id-card" href="/v1/identities/linkedin#linkedin-licenses-compatibility">
    What's supported
  </Card>

  <Card title="Sync, Rent, or Managed" icon="users" href="/v1/identities/sync-vs-managed">
    Choose your approach
  </Card>

  <Card title="Best Practices" icon="star" href="/v1/linkedin/best-practices">
    Avoid rate limits
  </Card>
</CardGroup>

### LinkedIn Webhooks

Get real-time notifications when account status changes:

| Event          | When it fires                  |
| -------------- | ------------------------------ |
| `AUTH_SUCCESS` | Account connected successfully |
| `AUTH_PENDING` | Awaiting verification          |
| `AUTH_FAILED`  | Connection failed              |
| `AUTH_EXPIRED` | Session expired                |
| `AUTH_UPDATED` | Credentials refreshed          |

<Tip>
  Webhooks are essential for maintaining reliable integrations. See [setup instructions](/v1/identities/linkedin#monitor-linkedin-integration-status-with-webhooks).
</Tip>

***

## Execution Modes

Edges supports three ways to run Actions:

<AccordionGroup>
  <Accordion title="Live Mode — Real-time results" icon="bolt" defaultOpen>
    * **Response:** Immediate (synchronous)
    * **Use case:** Single requests, real-time enrichment
    * **Endpoint:** `/run/live`

    ```bash theme={null}
    POST /v1/actions/linkedin-extract-people/run/live
    ```

    Best for most use cases due to simplicity.
  </Accordion>

  <Accordion title="Async Mode — Background processing" icon="clock">
    * **Response:** Run ID immediately, results via callback
    * **Use case:** Batch processing, large datasets
    * **Endpoint:** `/run/async`

    ```bash theme={null}
    POST /v1/actions/linkedin-extract-people/run/async
    ```

    Ideal when processing thousands of records or when real-time isn't required.

    See [Async & Callbacks](/v1/runs/callbacks) for implementation details.
  </Accordion>

  <Accordion title="Schedule Mode — Planned execution" icon="calendar">
    * **Response:** Schedule ID, results via callback on each run
    * **Use case:** Recurring tasks, campaigns, off-peak processing
    * **Endpoint:** `/run/schedule`

    ```bash theme={null}
    POST /v1/actions/linkedin-extract-people/run/schedule
    ```

    Define `schedule_at`, `cron`, and `timezone` for precise timing.

    See [Schedules](/v1/runs/schedules) for CRON examples.
  </Accordion>
</AccordionGroup>

***

## Data Model

For developers building deep integrations, here's the database schema showing entity relationships:

<Frame caption="Database schema: Identities, Integrations, Runs, and their relationships">
  <img src="https://mintcdn.com/edges/t_NKpJuh3g-fW2Dp/images/core/core-relations-v1.png?fit=max&auto=format&n=t_NKpJuh3g-fW2Dp&q=85&s=c522914c080103b9f86afa0810adb51d" width="1414" height="1430" data-path="images/core/core-relations-v1.png" />
</Frame>

<Tip>
  **Interactive version:** [View full diagram](https://drawsql.app/teams/edges/diagrams/embed-edges-data-v1)
</Tip>

***

## What's next?

<CardGroup cols={2}>
  <Card title="Set Up Identities" icon="user-plus" href="/v1/identities/add-manage-identities">
    Create and manage your first Identity
  </Card>

  <Card title="Connect LinkedIn" icon="linkedin" href="/v1/identities/linkedin">
    Link a LinkedIn account to an Identity
  </Card>

  <Card title="Browse Actions" icon="bolt" href="/v1/api/actions">
    Explore 60+ available Actions
  </Card>

  <Card title="TypeScript SDK" icon="code" href="/v1/sdk">
    Type-safe SDK for faster development
  </Card>
</CardGroup>