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

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

Warning

Treat the API key like a database password. Store it in a server environment variable. Never expose it through NEXT_PUBLIC_, browser fetch calls, static JavaScript, a mobile bundle, logs, screenshots, support tickets, or version control.

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

Scope	Permission
`platform:read`	Account, plan, add-on, and capability discovery
`listings:read`	Listing search, listing detail, nearby places, and typeahead
`leads:read`	List and read leads
`leads:write`	Create, update, and delete leads
`sites:read`	Read the website and active MLS board summary
`widgets:read`	Read widget definitions for the approved website
`widgets:write`	Create, configure, pause, and delete widgets for the approved website
`analytics:read`	Read site-scoped usage summaries
`homethread:read`	Read HomeThread collection summaries
`visitors:read`	Read registered visitor contact records
`saved-searches:read`	Read saved searches and alert status
`saved-listings:read`	Read saved listing identifiers
`team:read`	Read Brokerage team profiles
`clients:read`	Read Agency Partner client workspace summaries
`valuations:read`	Read valuation resources when the add-on is active
`valuations:write`	Create 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

Create a second key for the same website.
Deploy it to the server environment and verify a capabilities request.
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

Do not call the Developer Platform directly from untrusted client code. Put a narrow server endpoint between the client and EasyAgentIDX, return only the fields the interface needs, validate user input, and add your own user authorization where private resources such as leads are involved. Public EasyAgentIDX widgets remain the supported client-side option.

PreviousOverview NextPlatform Resources