> ## 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.

# Adding & Managing Identities

> Comprehensive guide to syncing Identities and Integrations with the Edges API v1.

The first step in using the Edges API (v1) to manage identities is to synchronize your SaaS users as identities with your Edges workspace.

Here's a quick recap of the ways Edges can adapt to your needs:

1. **White Label** – Fully branded solutions where Edges runs in the background, allowing your brand to take the spotlight.
2. **White Label — Stealth Mode** – Run Edges's API with managed LinkedIn accounts—no Chrome Extension required.
   Check out this article for more information: [LinkedIn Identities Options: Sync, Rent, or Use Managed](/v1/identities/sync-vs-managed)
3. **Grey Label** – Combine Edges's Chrome Extension with shared accounts, utilizing our branded Edges connection flow.

<Note>
  **Quick Start Option:** If you want to get started immediately without managing identities and integrations, you can use [Managed Mode](#managed-mode) which uses Edges's pre-configured accounts (1.5× credit cost).

  For comprehensive details about identity modes, see [Identity Modes: Direct, Auto, and Managed](/v1/identities/modes).
</Note>

When integrating your SaaS with Edges, it's important to understand the distinction between **Identities** and **Integrations**.

* **Identities**: Each user on your SaaS corresponds to an identity in Edges. Think of a identity as a **license** that enables automation for that individual.
* **Integrations**: Integrations are the specific integrations (like LinkedIn) attached to an identity, allowing them to run automations on specific platforms.

## **1. Create an Identity**

To enable automation for an Identity, create the identity by sending a **POST** request to the [Create an Identity](/v1/api/identities/create) endpoint:

```bash theme={null}
curl --request POST \
  --url https://api.edges.run/v1/identities \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your_api_key>' \
  --data '{
  "name": "John Doe or a reference for your identity",
  "timezone": "Europe/Paris",
  "type": "standard"
}'
```

<ParamField body="name" type="string">
  A name that allows you to identify the Identity: it can be the full name of the Identity or an internal reference (or both!) at your convenience.
</ParamField>

<ParamField body="timezone" type="string">
  The Identity's timezone.

  <Warning>
    The `timezone` field provisions a proxy IP matching that timezone/country.
    This needs to match the location where you log into your LinkedIn account to
    avoid restrictions.
  </Warning>

  <Info>
    Edges supports the [canonical IANA time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), as defined by the tz database. Only canonical names are accepted. Deprecated or alias entries are currently not supported.

    Example: "Europe/Kiev" is deprecated and has been replaced by "Europe/Kyiv", which is the valid canonical identifier. Deprecated names are maintained in the IANA backward zone file for legacy compatibility but should not be used.
  </Info>

  <Tip>
    When using a VPN, either

    1. Log out of your VPN before accessing social media, or
    2. Ensure the "timezone" you send matches the country of the VPN IP address.
  </Tip>
</ParamField>

<ParamField body="type" type="string">
  Specifies the type of identity. Determines billing and credit consumption behavior.

  * **`standard`** (default): Standard identity included in your plan. All actions consume credits at the normal rate.

  * **`engagement`**: Engagement identity that allows running a broad set of LinkedIn outreach actions (connect, message, follow, like, comment, etc.) **without consuming credits**. Ideal for building SaaS products or AI agents that enable users to engage on LinkedIn or create outreach sequences.

  <Warning>
    Engagement Identities must be **enabled first** from the [Developer Settings](https://app.edges.run/settings/developers) page and require billing details to be filled. They are **billed monthly** based on the peak number of active Engagement Identities during your billing cycle (starting at \$7.99/identity/month).
  </Warning>

  <Tip>
    Use Engagement Identities for high-volume, repetitive outreach actions (connect, message, follow) and keep standard identities for more occasional or data extraction workflows. See [Engagement Identities](/v1/identities/engagement) for more details.
  </Tip>
</ParamField>

### **Save the Identity's `uid`**

Once the request is successful, Edges will return an Identity's `uid`.

Save this as `identity_uid` in your own user database - you'll need it for:

* Connecting integrations for this Identity
* Launching actions, via the `identity_ids` field

<Note>
  💡 When launching an action, always pass the Identity's `uid` via the
  `identity_ids` field. You do not need to pass the Integration's UID.
</Note>

### **Identity Modes**

Edges supports three identity modes to control how accounts are used for action execution:

#### **Direct Mode**

Use specific identities for precise control:

```bash theme={null}
curl --request POST \
  --url 'https://api.edges.run/v1/actions/linkedin-extract-people/run/live' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "identity_mode": "direct",
    "identity_ids": ["identity-1", "identity-2"]
  }'
```

#### **Auto Mode**

Automatic distribution across all available accounts:

```bash theme={null}
curl --request POST \
  --url 'https://api.edges.run/v1/actions/linkedin-extract-people/run/live' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "identity_mode": "auto"
  }'
```

#### **Managed Mode**

Use Edges's pre-configured account pool (1.5× credit cost):

```bash theme={null}
curl --request POST \
  --url 'https://api.edges.run/v1/actions/linkedin-extract-people/run/live' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "identity_mode": "managed"
  }'
```

<Note>
  **Managed mode cost:** Using `identity_mode: "managed"` costs 1.5× the standard credit cost but requires no setup.
</Note>

For detailed comparisons and use case recommendations, see [LinkedIn Identities Options: Sync, Rent, or Use Managed](/v1/identities/sync-vs-managed).

## **2. Connect an Identity's Integration**

To run most automations, your identities must be linked to the platform(s) they'll act on, like LinkedIn.
This section walks you through creating an identity and connecting the necessary integrations using Edges's API.

Once you have created an identity, the next step is to attach an integration.
This integration enables the identity to automate specific platforms, like LinkedIn, through Edges.

### **Request Body**

To create or update an integration, use the **POST** method for the
[Connect an Identity's Integration](/v1/api/integrations/connect) endpoint.
Here's an example for a **COOKIES** integration type (like LinkedIn):

```bash theme={null}
curl --request POST \
  --url https://api.edges.run/v1/identities/{identity_uid}/integrations/linkedin \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your_api_key>' \
  --data '{
  "account_name": "LinkedIn Account #1",
  "auth_data": {
    "cookies": {
      "li_at": "<li_at_token>",
      "li_a": "<li_a_token>"
    }
  }
}'
```

<ParamField body="account_name" type="string">
  Name of the LinkedIn account, e.g. "LinkedIn Account #1". It's generally the
  User's `full_name` or `email`.
</ParamField>

<ParamField body="auth_data.cookies" type="object">
  For **COOKIES** integration types, provide authentication cookies here.

  <Note>
    **Important note**: If you're connecting an account for **LinkedIn Sales
    Navigator**, you need to send both cookies. If you don't include the `li_a`
    token, the connection may not work properly with LinkedIn Sales Navigator.
    Including the `li_a` token will also speed up account synchronization.
  </Note>
</ParamField>

### **Supported Authentication Types**

Edges supports the following integration types:

* **COOKIES**
* **BASIC**
* **OAUTH**
* **APIKEY**

Each type may require a slightly different request body.

### **Native LinkedIn Authentication**

You can also authenticate LinkedIn accounts using email and password credentials. This method uses Edges's native LinkedIn authentication system.

Here's an example request using the [Connect a LinkedIn Account (Username/Password)](/v1/api/linkedin/authentication) endpoint:

```bash theme={null}
curl --request POST \
  --url https://api.edges.run/v1/identities/{identity_uid}/integrations/linkedin \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "auth_data": {
    "basic": {
      "username": "elon@musk.com",
      "password": "********"
    }
  }
}'
```

<Note>**Important**: we encrypt everything for security reasons.</Note>

### **Native LinkedIn Login Link**

To simplify integration setup for your users, we handle all authentication complexity automatically.
Rather than building custom login forms and managing credentials, we provide secure, time-limited URLs (valid for 48 hours) that enable users to connect their accounts seamlessly.

These login links work with supported integrations like LinkedIn without requiring browser extensions or custom form handling.

When you create an Identity using our [Identity creation endpoint](/v1/api/identities/create), you'll receive these login links in the response:

```json theme={null}
{
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2023-10-01T12:00:00Z",
  "workspace_uid": "5678e456-e89b-12d3-a456-426614174001",
  "name": "John Doe",
  "timezone": "Europe/Paris",
  "integrations": [],
  "identity_login_links": {
    "linkedin": "https://app.edges.run/identities/linkedin/login?token=XXXXXX"
  }
}
```

You can share the login URL ([https://app.edges.run/identities/linkedin/login?token=XXXXXX](https://app.edges.run/identities/linkedin/login?token=XXXXXX)) via email, or embed it directly in your product interface as a button or link.

When clicked, users are taken to our secure, white-labeled authentication page to complete the LinkedIn connection process.

<Tip>
  This feature eliminates the need for browser extensions or custom login forms. Users can securely connect their LinkedIn accounts by simply visiting the provided login link, which works across all browsers and supports all security methods (including SMS, authenticator apps, and in-app confirmations).
</Tip>

If you need to generate new login links (for example, if the previous one expired), you can use the [Generate Login Links](/v1/api/identities/login-links) endpoint.

### Chrome Extension Connection Flow (Grey Label)

An alternative to the native login link is to use Edges's connection flow, which allows you to connect your users' accounts through our Chrome Extension.

Once the identity is created and you have the `identity_uid`, you can generate a connection link that will open the Edges Chrome Extension. The link format is:

`https://app.edges.run/integrations/linkedin/identities/{identity_uid}`

Replace `{identity_uid}` with the actual identity UID you received from the identity creation.

For example, if the identity UID of your new user is `ae369a13-dbd7-493a-bc05-dbbc49ca6c22`, the connection link would look like this:

```plaintext theme={null}
https://app.edges.run/integrations/linkedin/identities/ae369a13-dbd7-493a-bc05-dbbc49ca6c22
```

Share this link with your user, and they will install the Edges Chrome Extension to sync their account. Their LinkedIn account will then be linked to their Edges user.

<Note>
  The shared link is the same as the one you can get on your workspace at [https://app.edges.run/integrations/linkedin](https://app.edges.run/integrations/linkedin) for an existing identity. It will open the Edges Chrome Extension, which will handle the connection process.

  To understand the process, you can complete it directly on your workspace. See this step-by-step guide: [https://support.edges.run/en/articles/11588406-how-to-connect-an-identity-to-linkedin](https://support.edges.run/en/articles/11588406-how-to-connect-an-identity-to-linkedin).
</Note>