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 { client, Identities } from 'anchorbrowser';

client.setConfig({ auth: () => process.env.ANCHORBROWSER_API_KEY });

const identity = await Identities.createIdentity({
  body: {
    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_identity(
    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 Sessions.createSession({
  body: {
    session: {
      proxy: { active: true },
    },
    browser: {
      captcha_solver: { active: true },
      extra_stealth: { active: true },
    },
    identities: [{ id: identityId }],
  },
});

session = anchor_client.sessions.create_session(
    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`	Defaults to `true`: reuse the saved profile for active identities. Set `false` to validate the profile and re-authenticate only if it is stale.
`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 Tasks.runTask({
  path: { taskId },
  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. By default (identity_skip_validation: true), active identities reuse their saved profile. Pass identity_skip_validation: false, or call POST /v1/identities/{identityId}/reauthenticate, to validate the profile and re-authenticate if it is stale.

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 / re-auth requested, 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 (see below).

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.

Generate re-authenticate links

When an identity needs a fresh login, create a token or ready-to-share URL:

Endpoint	Returns
`POST /v1/identities/{identityId}/re-authenticate-token`	JWT token (build your own URL)
`POST /v1/identities/{identityId}/reauth-links`	`reauth_url` + `expires_at`

Both accept an optional request body:

Field	Description
`callbackUrl`	HTTPS redirect after the user finishes
`authMethod`	`profile` (manual login, default), `dynauth`, or `credentials`

Send the user to https://app.anchorbrowser.io/identity/re-authenticate?token={token} (or use reauth_url from reauth-links).

const { reauth_url } = await client.post(
  `/v1/identities/${identityId}/reauth-links`,
  { body: { authMethod: 'dynauth', callbackUrl: 'https://your-app.com/reauth-done' } },
);
window.location.href = reauth_url;

response = anchor_client.post(
    f"/v1/identities/{identity_id}/reauth-links",
    body={
        "authMethod": "dynauth",
        "callbackUrl": "https://your-app.com/reauth-done",
    },
)
reauth_url = response["reauth_url"]
# Redirect the user to reauth_url from your frontend

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 Identities.createIdentity({
  body: {
    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_identity(
    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 Applications.listApplicationIdentities({
  path: { applicationId: app.id },
  query: { metadata: JSON.stringify({ department: 'Engineering' }) },
});

import json

identities = anchor_client.applications.list_application_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

Generate re-authenticate links

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

​Generate re-authenticate links

​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

Generate re-authenticate links

Identity metadata

Creating an identity with metadata

Filtering identities by metadata

Related