> ## Documentation Index
> Fetch the complete documentation index at: https://docs.exchangeratesapi.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

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

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

## Getting Your API Key

### 1. Create Account

Sign up at [app.exchangeratesapi.com.au](https://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.

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

## 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:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.exchangeratesapi.com.au/latest \
    -H "Authorization: Bearer your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.exchangeratesapi.com.au/latest', {
    headers: {
      'Authorization': 'Bearer your_api_key_here'
    }
  });
  ```

  ```python Python theme={null}
  import requests

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

  response = requests.get(
      'https://api.exchangeratesapi.com.au/latest',
      headers=headers
  )
  ```

  ```php PHP theme={null}
  <?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);
  ?>
  ```
</CodeGroup>

## Security Best Practices

### Environment Variables

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

<CodeGroup>
  ```javascript JavaScript theme={null}
  // ✅ 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}`
    }
  });
  ```

  ```python Python theme={null}
  # ✅ 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 PHP theme={null}
  <?php
  // ✅ Good - Use environment variables
  $api_key = $_ENV['EXCHANGE_RATES_API_KEY'];

  $headers = [
      'Authorization: Bearer ' . $api_key
  ];
  ?>
  ```
</CodeGroup>

### 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

```javascript theme={null}
// ❌ 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:

```bash theme={null}
# ❌ 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](https://app.exchangeratesapi.com.au)
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:

<Steps>
  <Step title="Generate New Key">
    Create a new API key in your dashboard while keeping the old one active
  </Step>

  <Step title="Update Applications">
    Deploy your applications with the new API key
  </Step>

  <Step title="Verify Deployment">
    Ensure all applications are using the new key successfully
  </Step>

  <Step title="Revoke Old Key">
    Once confirmed, revoke the old API key to complete the rotation
  </Step>
</Steps>

## Authentication Errors

### Invalid API Key (401)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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  |

```bash theme={null}
# No authentication needed
curl https://api.exchangeratesapi.com.au/status
curl https://api.exchangeratesapi.com.au/symbols
```

## Testing Your Authentication

Use this simple test to verify your API key works:

<CodeGroup>
  ```bash cURL Test theme={null}
  curl -i https://api.exchangeratesapi.com.au/latest \
    -H "Authorization: Bearer your_api_key_here"
  ```

  ```javascript JavaScript Test theme={null}
  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();
  ```

  ```python Python Test theme={null}
  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()
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Rate Limits" icon="gauge" href="/guides/rate-limits">
    Understand your plan's quotas and limits
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Explore all available endpoints
  </Card>

  <Card title="Dashboard" icon="chart-line" href="https://app.exchangeratesapi.com.au">
    Manage your API keys and monitor usage
  </Card>

  <Card title="Best Practices" icon="shield" href="/guides/best-practices">
    Learn security and performance tips
  </Card>
</CardGroup>