> ## Documentation Index
> Fetch the complete documentation index at: https://test-62a57ffd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate your requests to the Brave Search API using subscription tokens

## Overview

The Brave Search API uses API key authentication to secure requests. Every API request must include your subscription token in the request header to authenticate and authorize access.

<Note>
  Your API key is confidential and should be kept secure. Never expose it in
  client-side code, public repositories, or share it publicly.
</Note>

## Obtaining Your API Key

To get started with the Brave Search API, you'll need a subscription token:

1. **Subscribe to a plan** — Visit the [Brave Search API](https://api-dashboard.search.brave.com/app/subscriptions/subscribe) page and choose a plan that fits your needs
2. **Access your API keys** — Once subscribed, navigate to the [API Keys section](https://api-dashboard.search.brave.com/app/keys) in your dashboard
3. **Copy your token** — Your subscription token will be displayed. Copy it to use in your requests

<Tip>
  Even on the Free plan, you need to subscribe to obtain an API key. You won't
  be charged for the free tier.
</Tip>

## Authentication Method

All requests to the Brave Search API must include your subscription token in the `X-Subscription-Token` HTTP header.

### Header Format

```
X-Subscription-Token: YOUR_API_KEY
```

## Code Examples

Here are examples of how to authenticate requests in various programming languages:

<CodeGroup>
  ```bash cURL theme={null}
  curl -s --compressed "https://api.search.brave.com/res/v1/web/search?q=brave+search" \
    -H "Accept: application/json" \
    -H "Accept-Encoding: gzip" \
    -H "X-Subscription-Token: YOUR_API_KEY"
  ```

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

  url = "https://api.search.brave.com/res/v1/web/search"
  headers = {
      "Accept": "application/json",
      "Accept-Encoding": "gzip",
      "X-Subscription-Token": "YOUR_API_KEY"
  }
  params = {
      "q": "brave search"
  }

  response = requests.get(url, headers=headers, params=params)
  data = response.json()
  print(data)
  ```

  ```javascript JavaScript (Node.js) theme={null}
  const axios = require("axios");

  const url = "https://api.search.brave.com/res/v1/web/search";
  const headers = {
    Accept: "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": "YOUR_API_KEY",
  };
  const params = {
    q: "brave search",
  };

  axios
    .get(url, { headers, params })
    .then((response) => {
      console.log(response.data);
    })
    .catch((error) => {
      console.error("Error:", error.response?.data || error.message);
    });
  ```

  ```javascript JavaScript (Fetch) theme={null}
  const url = new URL("https://api.search.brave.com/res/v1/web/search");
  url.searchParams.append("q", "brave search");

  fetch(url, {
    method: "GET",
    headers: {
      Accept: "application/json",
      "Accept-Encoding": "gzip",
      "X-Subscription-Token": "YOUR_API_KEY",
    },
  })
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));
  ```

  ```go Go theme={null}
  package main

  import (
      "encoding/json"
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      url := "https://api.search.brave.com/res/v1/web/search?q=brave+search"

      req, err := http.NewRequest("GET", url, nil)
      if err != nil {
          panic(err)
      }

      req.Header.Add("Accept", "application/json")
      req.Header.Add("Accept-Encoding", "gzip")
      req.Header.Add("X-Subscription-Token", "YOUR_API_KEY")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      body, err := io.ReadAll(resp.Body)
      if err != nil {
          panic(err)
      }

      var result map[string]interface{}
      json.Unmarshal(body, &result)
      fmt.Println(result)
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI('https://api.search.brave.com/res/v1/web/search')
  uri.query = URI.encode_www_form(q: 'brave search')

  request = Net::HTTP::Get.new(uri)
  request['Accept'] = 'application/json'
  request['Accept-Encoding'] = 'gzip'
  request['X-Subscription-Token'] = 'YOUR_API_KEY'

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  data = JSON.parse(response.body)
  puts data
  ```

  ```php PHP theme={null}
  <?php

  $url = 'https://api.search.brave.com/res/v1/web/search?q=brave+search';

  $headers = [
      'Accept: application/json',
      'Accept-Encoding: gzip',
      'X-Subscription-Token: YOUR_API_KEY'
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_ENCODING, 'gzip');

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  print_r($data);

  ?>
  ```
</CodeGroup>

## Best Practices

### Secure Storage

Never hardcode your API key directly in your source code. Instead, use environment variables or secure configuration management:

<CodeGroup>
  ```python Python theme={null}
  import os

  api_key = os.environ.get('BRAVE_API_KEY')
  headers = {
      'X-Subscription-Token': api_key
  }
  ```

  ```javascript JavaScript theme={null}
  const apiKey = process.env.BRAVE_API_KEY;
  const headers = {
    "X-Subscription-Token": apiKey,
  };
  ```

  ```bash Environment Variable theme={null}
  export BRAVE_API_KEY="your_actual_api_key_here"
  ```
</CodeGroup>

### Key Rotation

Regularly rotate your API keys as a security best practice. You can generate new keys from your dashboard.

<Warning>
  If you suspect your API key has been compromised, immediately revoke it from
  your dashboard and generate a new one.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Overview" icon="book" href="/getting-started/overview">
    Learn about available endpoints and features
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore detailed API documentation
  </Card>
</CardGroup>