Identities

An identity is a specific account on an application — for example “John’s LinkedIn” or “Acme Corp Salesforce admin.” When you attach an identity to a session or task, Anchor signs in on your behalf before automation runs.

What an identity contains

An identity is more than a username and password. After a successful login, Anchor persists everything needed to stay signed in:

Component	What it stores	Enables
Credentials	Username/password, TOTP secrets, 1Password refs, email MFA mailbox, custom fields — depending on the application’s auth flow	Full re-login when the saved session expires
Browser profile	Cookies, local storage, and session state from the last successful sign-in	Fast startup when the site still considers the session valid
Auth flow	Which login methods this identity uses (linked from the application)	Consistent login behavior across re-authentication
Status	Whether the identity is ready to use (`active`, `validated`) or needs attention (`failed`, `agent_failed`)	Knowing if automation can proceed without intervention

What Anchor can do on the next run depends on what was saved. An identity with credentials and a valid browser profile starts signed in immediately. An identity with only a browser profile (for example after manual login) works until the site expires the session — then someone must sign in again.

Quick start: create an identity

Create an identity with credentials for the target application. If the application uses a preset auth flow, pass authOptionId with the flow ID.

import Anchorbrowser from 'anchorbrowser';

const anchorClient = new Anchorbrowser();

const identity = await anchorClient.identities.create({
  source: 'https://linkedin.com',
  name: 'John Doe',
  credentials: [{
    type: 'username_password',
    username: 'john@example.com',
    password: 'secret',
  }],
});

console.log(identity.id);

from anchorbrowser import Anchorbrowser

anchor_client = Anchorbrowser()

identity = anchor_client.identities.create(
    source="https://linkedin.com",
    name="John Doe",
    credentials=[{
        "type": "username_password",
        "username": "john@example.com",
        "password": "secret",
    }],
)

print(identity.id)

For end-user self-service authentication in your app, use Embedding End-User Authentication UI.

Use an identity in browser sessions

Pass the identity ID in the identities array when creating a session. Anchor authenticates before your agent or automation starts.

const session = await anchorClient.sessions.create({
  session: {
    proxy: { active: true },
  },
  browser: {
    captcha_solver: { active: true },
    extra_stealth: { active: true },
  },
  identities: [{ id: identityId }],
});

session = anchor_client.sessions.create(
    session={"proxy": {"active": True}},
    browser={
        "captcha_solver": {"active": True},
        "extra_stealth": {"active": True},
    },
    identities=[{"id": identity_id}],
)

Optional session flags:

Flag	Effect
`identity_skip_validation`	Skip checking whether the saved browser profile is still signed in
`identity_async_auth`	Run authentication in the background and return the session immediately

Use an identity in tasks

Pass identity_id when running an Automation Task. Anchor creates a browser session, authenticates with the identity, then executes the task.

const run = await anchorClient.post(`/v2/tasks/${taskId}/run`, {
  body: {
    input_params: { report_name: 'Monthly Invoice' },
    identity_id: identityId,
  },
});

import os
from anchorbrowser import Anchorbrowser

anchor_client = Anchorbrowser(api_key=os.getenv('ANCHOR_API_KEY'))

run = anchor_client.post(
    f'/v2/tasks/{task_id}/run',
    body={
        'input_params': {'report_name': 'Monthly Invoice'},
        'identity_id': identity_id,
    },
)

You can also pass session_id to run a task inside an existing authenticated session, or set identity_skip_validation to skip profile validation before the run.

When Anchor re-authenticates

Each time a session or task starts with an identity attached, Anchor decides whether a full login is needed:

Browser profile is still valid — Anchor loads the saved profile and the session starts signed in. No login steps run.
Browser profile expired, credentials available — Anchor runs the application’s auth flow using stored credentials (including MFA methods like email OTP or authenticator). The profile is refreshed for next time.
Browser profile expired, no credentials — Common for manual-login identities. Anchor cannot re-authenticate automatically. Sign in again via the dashboard or generate a re-authenticate link with POST /v1/identities/{identityId}/re-authenticate-token.

Re-authentication requires the identity to have the credentials or auth flow needed for the site’s login steps. If the site adds a new MFA requirement that wasn’t saved on the identity, update the identity or re-authenticate manually.

Identity metadata

Add custom metadata to identities for filtering and organization. Metadata is a flexible key-value store.

Creating an identity with metadata

const identity = await anchorClient.identities.create({
  source: 'https://linkedin.com',
  name: 'John Doe',
  metadata: {
    department: 'Engineering',
    role: 'admin',
  },
  credentials: [{
    type: 'username_password',
    username: 'john@example.com',
    password: 'secret',
  }],
});

identity = anchor_client.identities.create(
    source="https://linkedin.com",
    name="John Doe",
    metadata={
        "department": "Engineering",
        "role": "admin",
    },
    credentials=[{
        "type": "username_password",
        "username": "john@example.com",
        "password": "secret",
    }],
)

Filtering identities by metadata

const identities = await anchorClient.applications.listIdentities(app.id, {
  metadata: JSON.stringify({ department: 'Engineering' }),
});

import json

identities = anchor_client.applications.list_identities(
    application_id=app.id,
    metadata=json.dumps({"department": "Engineering"}),
)

Managed Authentication Overview

Profiles vs identities and how everything connects

Applications

Configure target sites and auth flows

Run a Task

Execute automation tasks with an identity

Embedding End-User Auth UI

Let end users connect accounts from your product

Email MFA

Email OTP via forwarded inbox

API Reference

Identity endpoints

Introduction

Platform

Integrations

Account

What an identity contains

Quick start: create an identity

Use an identity in browser sessions

Use an identity in tasks

When Anchor re-authenticates

Identity metadata

Creating an identity with metadata

Filtering identities by metadata

Managed Authentication Overview

Applications

Run a Task

Embedding End-User Auth UI

Email MFA

API Reference

​What an identity contains

​Quick start: create an identity

​Use an identity in browser sessions

​Use an identity in tasks

​When Anchor re-authenticates

​Identity metadata

​Creating an identity with metadata

​Filtering identities by metadata

​Related

Managed Authentication Overview

Applications

Run a Task

Embedding End-User Auth UI

Email MFA

API Reference

What an identity contains

Quick start: create an identity

Use an identity in browser sessions

Use an identity in tasks

When Anchor re-authenticates

Identity metadata

Creating an identity with metadata

Filtering identities by metadata

Related