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/developerand 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.
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
| 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 |
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
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.