Skip to article

Authentication

EasyAgentIDX uses site-bound bearer keys. Each key belongs to one account and one verified website with an active MLS approval. The key can only use the scopes and platform capabilities allowed by the account plan.

Create a key

  1. Add and verify the website in your EasyAgentIDX dashboard.
  2. Complete MLS approval for that website.
  3. Open /my/developer and select New Key.
  4. Select the approved website and only the scopes your application needs.
  5. Copy the secret immediately. EasyAgentIDX stores only its secure hash and cannot show it again.

Store the key as EASYAGENTIDX_API_KEY in your server environment. Your backend uses it to authenticate requests, while your browser or mobile interface receives the application data it needs. Keep the value in your deployment secret store, separate from source code and client bundles.

Required headers

Authorization: Bearer eai_1234abcd5678ef90.<secret>
X-EAI-Site-ID: site_0123456789abcdef

The site identifier is public, but it is still required on every request. It must exactly match the website selected when the key was created. Query string substitutes are not accepted.

Server-side example

// Next.js Server Component or Route Handler
const response = await fetch(
  "https://app.easyagentidx.com/api/v1/search?location=La%20Jolla%2C%20CA",
  {
    headers: {
      Authorization: `Bearer ${process.env.EASYAGENTIDX_API_KEY}`,
      "X-EAI-Site-ID": process.env.EASYAGENTIDX_SITE_ID,
    },
    cache: "no-store",
  }
);

Scopes

ScopePermission
platform:readAccount, plan, add-on, and capability discovery
listings:readListing search, listing detail, nearby places, and typeahead
leads:readList and read leads
leads:writeCreate, update, and delete leads
sites:readRead the website and active MLS board summary
widgets:readRead widget definitions for the approved website
widgets:writeCreate, configure, pause, and delete widgets for the approved website
analytics:readRead site-scoped usage summaries
homethread:readRead HomeThread collection summaries
visitors:readRead registered visitor contact records
saved-searches:readRead saved searches and alert status
saved-listings:readRead saved listing identifiers
team:readRead Brokerage team profiles
valuations:readRead valuation resources when the add-on is active
valuations:writeCreate an AVM estimate and consume a credit

The dashboard does not issue wildcard keys. A requested scope that is not included with the account plan is rejected by the server.

Owners can authorize scopes included with the plan. Admins can authorize only scopes covered by their dashboard permissions. Developer-role users can issue non-PII read scopes for platform discovery, listings, sites, widgets, and analytics. An Owner or authorized Admin must issue keys that access private customer records or change resources.

New write scopes are optional. Existing keys retain their original scopes. Create a replacement key with the required permission when adding widget management to an integration.

Site and tenant isolation

The server resolves the account, verified website, and active MLS feed from the credential record. It does not trust caller-provided account IDs, feed IDs, domains, or internal site IDs. Resource lookups also include the authenticated account before returning data.

Rotate without downtime

  1. Create a second key for the same website.
  2. Deploy it to the server environment and verify a capabilities request.
  3. Revoke the old key from the dashboard.

Each website can have up to two active keys so a controlled rotation can overlap briefly.

Browser and mobile applications

Connect your browser or mobile interface through your backend. Validate input, return the fields your interface needs and authorize each user before accessing private resources such as leads. For ready-made client-side experiences, embed EasyAgentIDX widgets directly on your website.