Authentication

The PropertyBase API supports multiple authentication methods for different use cases.

Authentication Methods

Method	Use Case	Expiry
API Key	Server-to-server	Never (until revoked)
OAuth 2.0	User authorization	Access: 1 hour, Refresh: 30 days
Session Token	Browser apps	24 hours

API Keys

API keys are the simplest way to authenticate server-to-server requests.

Creating an API Key

1. Go to Settings > API Keys
2. Click Create API Key
3. Enter a name for the key
4. Select permissions (scopes)
5. Copy the generated key immediately

warning

API keys are only shown once. Store them securely!

Using API Keys

Include the key in the Authorization header:

curl -X GET https://api.propertybase.ai/v1/leads \
  -H "Authorization: Bearer pb_live_xxxxxxxxxxxxx"

API Key Scopes

Scope	Description
read:properties	Read property data
write:properties	Create/update properties
read:leads	Read lead data
write:leads	Create/update leads
read:agents	Read agent data
write:agents	Create/update agents
read:analytics	Read analytics data
webhooks	Manage webhooks
admin	Full administrative access

Revoking API Keys

1. Go to Settings > API Keys
2. Find the key to revoke
3. Click Revoke
4. Confirm revocation

OAuth 2.0

OAuth 2.0 is used for applications that act on behalf of users.

OAuth Flow

1. User clicks "Connect PropertyBase"
2. Redirect to authorization URL
3. User grants permission
4. Receive authorization code
5. Exchange code for tokens
6. Use access token for API calls

Authorization URL

Redirect users to:

https://auth.propertybase.ai/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=read:leads%20write:leads&
  state=random_state_string

Parameters:

Parameter	Required	Description
client_id	Yes	Your OAuth client ID
redirect_uri	Yes	Your callback URL
response_type	Yes	Must be code
scope	Yes	Space-separated scopes
state	Recommended	CSRF protection token

Token Exchange

Exchange the authorization code for tokens:

curl -X POST https://auth.propertybase.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://yourapp.com/callback"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
  "scope": "read:leads write:leads"
}

Refreshing Tokens

When the access token expires, use the refresh token:

curl -X POST https://auth.propertybase.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

Using Access Tokens

curl -X GET https://api.propertybase.ai/v1/leads \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Best Practices

Security

1. Never expose API keys in client-side code
2. Use environment variables to store credentials
3. Rotate keys regularly (every 90 days recommended)
4. Use minimum required scopes
5. Monitor API key usage in the dashboard

Error Handling

Handle authentication errors gracefully:

try {
  const response = await fetch('/v1/leads', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  if (response.status === 401) {
    // Token expired or invalid
    await refreshToken();
    // Retry request
  }

  if (response.status === 403) {
    // Insufficient permissions
    throw new Error('Access denied');
  }
} catch (error) {
  console.error('API error:', error);
}

Token Storage

Token Type	Storage Recommendation
API Key	Environment variable, secrets manager
Access Token	Memory (not localStorage)
Refresh Token	Secure HTTP-only cookie, encrypted storage

Testing

Test API Keys

Create test keys with limited scope:

1. Go to Settings > API Keys
2. Click Create Test Key
3. Test keys have pb_test_ prefix
4. Cannot access production data

Sandbox Environment

Use our sandbox for testing:

https://api.sandbox.propertybase.ai/v1

Sandbox data is reset weekly.

Troubleshooting

Common Errors

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}

• Check the API key is correct
• Verify the key hasn't been revoked
• For OAuth, refresh the access token

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}

• Check the API key has required scopes
• Verify the user has access to the resource