Authentication

Learn how to authenticate with the StreetVerify API using API keys.

StreetVerify uses API key authentication for all public API endpoints. API keys provide secure access to our geocoding and address verification services.

API Key Authentication

API keys are used to authenticate requests to StreetVerify’s core geocoding and address verification services.

Creating an API Key

  1. Log in to your StreetVerify Dashboard
  2. Navigate to API Keys section
  3. Click Create New Key
  4. Give your key a descriptive name
  5. Copy the generated key immediately (it won’t be shown again)

API Key Format

StreetVerify API keys follow a secure format:

  • All keys start with sv_ followed by 32 random characters
  • Example: sv_1234567890abcdef1234567890abcdef

Using Your API Key

Include your API key in the Authorization header of every request:

Authorization: Bearer sv_1234567890abcdef...

Example Request

Using cURL

curl -X GET "https://core.streetverify.com/api/v1/geocode?address=1600%20Amphitheatre%20Parkway%2C%20Mountain%20View%2C%20CA" \
  -H "Authorization: Bearer YOUR_API_KEY"

Using JavaScript

const response = await fetch('https://core.streetverify.com/api/v1/geocode?address=1600%20Amphitheatre%20Parkway%2C%20Mountain%20View%2C%20CA', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();

Using Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(
    'https://core.streetverify.com/api/v1/geocode',
    params={'address': '1600 Amphitheatre Parkway, Mountain View, CA'},
    headers=headers
)
data = response.json()

API Key Security

  • Keep your API keys secure - Never expose them in client-side code or public repositories
  • Use environment variables - Store keys in environment variables, not in your code
  • Rotate keys regularly - Generate new keys periodically for enhanced security
  • Monitor usage - Track your API usage in the dashboard

Authentication Errors

Common Error Responses

Missing Authentication

{
  "error": "No authorization header provided",
  "code": "AUTH_MISSING"
}

Status Code: 401 Unauthorized

Invalid API Key

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Status Code: 401 Unauthorized

Insufficient Balance

{
  "error": "Insufficient balance. Please add funds to continue.",
  "code": "INSUFFICIENT_BALANCE",
  "balance": 0.00
}

Status Code: 402 Payment Required

Rate Limited

{
  "error": "Rate limit exceeded. Please try again later.",
  "code": "RATE_LIMITED",
  "retry_after": 60
}

Status Code: 429 Too Many Requests

Best Practices

  1. Production vs Development Keys

  2. Server-Side Usage

    • Always make API calls from your server
    • Never expose API keys in client-side JavaScript

  3. Key Rotation

    • Rotate keys every 90 days
    • Update your applications when rotating keys

  4. Environment Variables

    • Store API keys in environment variables
    • Use .env files for local development (never commit these)

  5. Monitoring

    • Monitor your API usage in the dashboard
    • Set up alerts for unusual activity

Code Examples

API Key Authentication Helper

class StreetVerifyClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://core.streetverify.com';
  }

  async request(endpoint, params = {}) {
    const url = new URL(`${this.baseUrl}${endpoint}`);
    Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));
    
    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    if (!response.ok) {
      throw new Error(`API Error: ${response.statusText}`);
    }
    
    return response.json();
  }
}

// Usage
const client = new StreetVerifyClient('YOUR_API_KEY');
const result = await client.request('/api/v1/geocode', {
  address: '1600 Amphitheatre Parkway, Mountain View, CA'
});

Next Steps