Token Authentication Guide

📘 Purpose

This document provides instructions and example code to authenticate with the RealtyFeed API using client credentials to retrieve an access token. The token is required for accessing secured endpoints in the API.

🔐 Authentication Methods

There are two primary ways to authenticate with the RealtyFeed API:

HTTP Header Authentication - Using Basic Authentication by passing base64-encoded client_id and client_secret in the HTTP request header.
Body Authentication - Passing client_id and client_secret directly in the request body.

1. HTTP Header Authentication (Basic Authentication)

In this authentication method, you pass the credentials (client_id and client_secret) as a base64-encoded string in the Authorization header, using the Basic authentication scheme.

This approach follows the OAuth 2.0 specification (RFC 6749, section 2.3.1), which recommends using HTTP Basic authentication for confidential clients when sending client credentials to the token endpoint.

Endpoint

URL: https://api.realtyfeed.com/v1/auth/token
Method: POST

cURL Example (Command Line)

To authenticate using Basic Authentication, encode your client_id and client_secret in base64 and include them in the Authorization header like this:

curl -X POST 'https://api.realtyfeed.com/v1/auth/token' \
--header 'Authorization: Basic ODhiN2M3M....'

The string ODhiN2M3M.... is a base64-encoded version of client_id:client_secret.
Format: Authorization: Basic {base64_encoded(client_id:client_secret)}

Postman Example

Open Postman.
Create a new POST request.
Set the URL to: https://api.realtyfeed.com/v1/auth/token.
Go to the Headers tab.
Add the following header:
- Authorization: Basic YOUR_BASE64_ENCODED_CLIENT_ID:CLIENT_SECRET
Note: Replace YOUR_BASE64_ENCODED_CLIENT_ID:CLIENT_SECRET with your actual base64-encoded credentials.
Click Send.

The response should contain the access token or an error message.

2. Body Authentication (Passing `client_id` and `client_secret` in the Request Body)

In this authentication method, you pass client_id and client_secret directly in the body of the POST request.

Endpoint

URL: https://api.realtyfeed.com/v1/auth/token
Method: POST
Content-Type: application/x-www-form-urlencoded

cURL Example (Command Line)

curl -X POST https://api.realtyfeed.com/v1/auth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Postman Example

Open Postman.
Create a new POST request.
Set the URL to: https://api.realtyfeed.com/v1/auth/token.
Go to the Body tab.
Choose x-www-form-urlencoded.
Add two key-value pairs:
- client_id: YOUR_CLIENT_ID
- client_secret: YOUR_CLIENT_SECRET
Click Send.

The response will contain the access token or an error message.

📦 Response Schema & Status Codes

✅ Success Response

HTTP Status Code: 200 OK

{
  "access_token": "eyJraW...",  // JWT used for authorization
  "expires_in": 86400,          // Token lifetime in seconds (e.g., 86400 = 24 hours)
  "token_type": "Bearer"        // Authentication scheme
}

Field	Type	Description

Field	Type	Description
`access_token`	string	JWT access token used for API requests
`expires_in`	integer	Token lifetime in seconds (e.g., 86400)
`token_type`	string	Typically `"Bearer"`

Error Response: Invalid Credentials

HTTP Status Code: 400 Bad Request

{
  "err": "Invalid client_id or client_secret"
}

Error Response: Too Many Attempts

HTTP Status Code: 403 Forbidden

{
  "err": "Too many failed attempts. Please try again after 1 hour."
}

Forcing a New Token (When Necessary)

A token (or API key) can be restricted by origin (domain) and/or IP address to enhance security. If you configure restrictions in API Key Settings, every request must comply with those rules.

If no restrictions are set, the key is valid from any origin or IP.
If restrictions are defined, every request must match the configured allowed origins and/or allowed IPs.

❌ Non‑compliant requests (origin/IP mismatch):

The API returns 403 Forbidden.
The token used in that request is blocked for one hour.
While blocked, that token cannot be used for any requests. After one hour, it becomes valid again, but will be blocked again if requests are still non‑compliant.

⚠️ If a token is blocked repeatedly, rotate it or request a new token via the authentication endpoint.

See: API Key Settings (internal Confluence) for configuring allowed origins and IPs.

If your token is blocked (403) or compromised, you may request a brand‑new token by passing the query parameter force_new_token=true to the token endpoint. This is rate‑limited (max 50 per day) and resets daily at 00:00 UTC.

cURL

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  "https://api.realtyfeed.com/v1/auth/token?force_new_token=true"

Example Response

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 86400,
    "token_type": "Bearer",
    "force_new_token_info": {
        "force_new_token_count": 2,
        "force_new_token_count_limit": 50,
        "force_new_token_count_reset_info": "force_new_token_count will be reset daily at 00:00 UTC"
    }
}

Best Practice: Prefer the default /auth/token flow. Only use force_new_token=true (as a query parameter) for 403‑blocked or compromised tokens.

🐍 Python Example

HTTP Header Authentication (Basic Authentication)

Better Code Block

Body Authentication

Better Code Block

Refer to the document Realtyfeed API Token: Fetch, Cache, and Use (Python + cURL) for additional examples

🌐 JavaScript (Fetch API) Example

HTTP Header Authentication (Basic Authentication)

Better Code Block

Body Authentication

Better Code Block

Refer to the document Realtyfeed API Token: Fetch, Cache, and Use (JavaScript + cURL) for additional examples.

🐘 PHP Example (cURL)

HTTP Header Authentication (Basic Authentication)

Better Code Block

Body Authentication

Better Code Block

🔐 Security Best Practices

Never expose your client_secret in frontend apps.
Store credentials in environment variables or a secure config system.
Use HTTPS for all requests.
Rotate secrets periodically.

📎 Using the Access Token

For authorized API calls (calls APIs retrieve data, not the token), include the access token in the Authorization header as follows:

Authorization: Bearer YOUR_ACCESS_TOKEN

Where YOUR_ACCESS_TOKEN is the token you obtained from the authentication process.

Token Authentication Guide

📘 Purpose

1. HTTP Header Authentication (Basic Authentication)

Endpoint

cURL Example (Command Line)

Postman Example

2. Body Authentication (Passing client_id and client_secret in the Request Body)

Endpoint

cURL Example (Command Line)

Postman Example

📦 Response Schema & Status Codes

✅ Success Response

Error Response: Invalid Credentials

Error Response: Too Many Attempts

Forcing a New Token (When Necessary)

Example Response

🐍 Python Example

HTTP Header Authentication (Basic Authentication)

Body Authentication

🌐 JavaScript (Fetch API) Example

HTTP Header Authentication (Basic Authentication)

Body Authentication

🐘 PHP Example (cURL)

HTTP Header Authentication (Basic Authentication)

Body Authentication

🔐 Security Best Practices

📎 Using the Access Token

2. Body Authentication (Passing `client_id` and `client_secret` in the Request Body)