Skip to content

authentication.mdx

Latest commit

 

History

History
368 lines (287 loc) · 8.2 KB

authentication.mdx

File metadata and controls

368 lines (287 loc) · 8.2 KB
title Authentication
description Learn how to authenticate with the Exchange Rates API using bearer tokens and API keys

API Key Overview

The Exchange Rates API uses Bearer Token authentication with unique API keys. All authenticated endpoints require an API key passed in the Authorization header.

API keys are unique to your account and should be kept secure. Never share your API key or commit it to version control.

Getting Your API Key

1. Create Account

Sign up at app.exchangeratesapi.com.au using your email address.

2. Verify Email

Click the magic link in your email to verify your account and access the dashboard.

3. Generate API Key

In the dashboard, click "Generate New API Key" to create your unique API key.

Your API key is only displayed once for security reasons. Make sure to copy and store it securely immediately after generation.

API Key Format

API keys follow this format: {suburb}_{unique_identifier}

buderim_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
  • Suburb prefix: Each key gets a unique Australian suburb name (e.g., buderim, montville, noosa)
  • Unique identifier: 56-character alphanumeric string
  • Total length: ~65 characters

Authentication Methods

Bearer Token (Recommended)

Pass your API key in the Authorization header using the Bearer scheme:

curl https://api.exchangeratesapi.com.au/latest \
  -H "Authorization: Bearer your_api_key_here"
const response = await fetch('https://api.exchangeratesapi.com.au/latest', {
  headers: {
    'Authorization': 'Bearer your_api_key_here'
  }
});
import requests

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

response = requests.get(
    'https://api.exchangeratesapi.com.au/latest',
    headers=headers
)
<?php
$headers = [
    'Authorization: Bearer your_api_key_here'
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.exchangeratesapi.com.au/latest',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($curl);
?>

Security Best Practices

Environment Variables

Store your API key in environment variables, never hardcode it:

// ✅ Good - Use environment variables
const API_KEY = process.env.EXCHANGE_RATES_API_KEY;

const response = await fetch('https://api.exchangeratesapi.com.au/latest', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
});
# ✅ Good - Use environment variables
import os
import requests

api_key = os.getenv('EXCHANGE_RATES_API_KEY')

headers = {
    'Authorization': f'Bearer {api_key}'
}

response = requests.get(
    'https://api.exchangeratesapi.com.au/latest',
    headers=headers
)
<?php
// ✅ Good - Use environment variables
$api_key = $_ENV['EXCHANGE_RATES_API_KEY'];

$headers = [
    'Authorization: Bearer ' . $api_key
];
?>

Server-Side Only

API keys should only be used in server-side applications. Never expose API keys in:

  • Frontend JavaScript code
  • Mobile applications
  • Client-side frameworks (React, Vue, Angular)
  • Browser developer tools
  • Version control systems
// ❌ Bad - Never do this in frontend code
const API_KEY = 'your_api_key_here'; // Exposed to users!

// ✅ Good - Call your backend API instead
const response = await fetch('/api/exchange-rates');

HTTPS Only

All API requests must use HTTPS. HTTP requests will be rejected:

# ❌ Bad - HTTP not allowed
curl http://api.exchangeratesapi.com.au/latest

# ✅ Good - HTTPS required
curl https://api.exchangeratesapi.com.au/latest

Managing API Keys

Key Status

API keys can have the following statuses:

  • Active: Key is valid and can make requests
  • Revoked: Key has been disabled and cannot make requests
  • Suspended: Account is suspended (billing issues, etc.)

Revoking Keys

If your API key is compromised:

  1. Log into your dashboard
  2. Find your API key in the list
  3. Click "Revoke" to immediately disable it
  4. Generate a new API key
  5. Update your applications with the new key

Key Rotation

For security, we recommend rotating your API keys periodically:

Create a new API key in your dashboard while keeping the old one active Deploy your applications with the new API key Ensure all applications are using the new key successfully Once confirmed, revoke the old API key to complete the rotation

Authentication Errors

Invalid API Key (401)

{
  "success": false,
  "error": {
    "code": 401,
    "type": "invalid_api_key",
    "info": "Invalid or missing API key."
  }
}

Common causes:

  • Missing Authorization header
  • Incorrect Bearer token format
  • API key has been revoked
  • Typo in the API key

Account Suspended (401)

{
  "success": false,
  "error": {
    "code": 401,
    "type": "account_suspended",
    "info": "Account is suspended. Please contact support."
  }
}

Common causes:

  • Billing issues (overdue payments)
  • Terms of service violations
  • Suspicious activity detected

Rate Limit Exceeded (429)

{
  "success": false,
  "error": {
    "code": 429,
    "type": "rate_limit_exceeded",
    "info": "Daily quota exceeded. Upgrade your plan or try again tomorrow."
  }
}

Public Endpoints (No Auth Required)

Some endpoints don't require authentication:

Endpoint Description Rate Limit
GET /status API operational status Unlimited
GET /symbols List supported currencies Unlimited
GET /convert (free) Limited conversion 3/hour per IP 
# No authentication needed
curl https://api.exchangeratesapi.com.au/status
curl https://api.exchangeratesapi.com.au/symbols
curl "https://api.exchangeratesapi.com.au/convert?from=AUD&to=USD&amount=100"

Testing Your Authentication

Use this simple test to verify your API key works:

curl -i https://api.exchangeratesapi.com.au/latest \
  -H "Authorization: Bearer your_api_key_here"
async function testAuth() {
  try {
    const response = await fetch('https://api.exchangeratesapi.com.au/latest', {
      headers: {
        'Authorization': 'Bearer your_api_key_here'
      }
    });
    
    const data = await response.json();
    
    if (data.success) {
      console.log('✅ Authentication successful');
      console.log(`Plan: ${data.plan || 'free'}`);
    } else {
      console.log('❌ Authentication failed:', data.error.info);
    }
  } catch (error) {
    console.log('❌ Request failed:', error.message);
  }
}

testAuth();
import requests

def test_auth():
    try:
        response = requests.get(
            'https://api.exchangeratesapi.com.au/latest',
            headers={'Authorization': 'Bearer your_api_key_here'}
        )
        
        data = response.json()
        
        if data.get('success'):
            print('✅ Authentication successful')
            print(f"Plan: {data.get('plan', 'free')}")
        else:
            print(f'❌ Authentication failed: {data["error"]["info"]}')
            
    except Exception as error:
        print(f'❌ Request failed: {error}')

test_auth()

Next Steps

Understand your plan's quotas and limits Explore all available endpoints Manage your API keys and monitor usage Learn security and performance tips