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

# Authentication

> Learn how to authenticate your API requests

## API Key Authentication

Trestle controls access to the API and data via an API Key. The API key is the primary authentication method for your account. Your usage is recorded and reported via the API Key. You may use a single API key for multiple Trestle APIs.

## Getting an API Key

To get an API key:

1. [Sign up for a Developer Portal account](https://portal.trestleiq.com/signup)
2. Once approved, you can send a request to any of Trestle's APIs
3. Your API key will be available in the Developer Portal

## Using Your API Key

All API requests require authentication via the `x-api-key` header.

### Header Format

Include your API key in the request header:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
x-api-key: YOUR_API_KEY
```

### Example Request

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request GET \
    --url "https://api.trestleiq.com/3.0/phone_intel?phone=2069735100" \
    --header "x-api-key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://api.trestleiq.com/3.0/phone_intel?phone=2069735100",
    {
      headers: {
        "x-api-key": "YOUR_API_KEY",
      },
    }
  );
  const data = await response.json();
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import axios from "axios";

  const { data } = await axios.get(
    "https://api.trestleiq.com/3.0/phone_intel?phone=2069735100",
    {
      headers: {
        "x-api-key": "YOUR_API_KEY",
      },
    }
  );
  console.log(data);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  headers = {"x-api-key": "YOUR_API_KEY"}

  response = requests.get(
      "https://api.trestleiq.com/3.0/phone_intel",
      params={"phone": "2069735100"},
      headers=headers,
      timeout=30,
  )
  data = response.json()
  print(data)
  ```

  ```csharp C# theme={"theme":{"light":"github-light","dark":"github-dark"}}
  using var client = new HttpClient();
  client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

  var response = await client.GetAsync("https://api.trestleiq.com/3.0/phone_intel?phone=2069735100");
  var body = await response.Content.ReadAsStringAsync();
  Console.WriteLine(body);
  ```

  ```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
  package main

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

  func main() {
  	req, _ := http.NewRequest("GET", "https://api.trestleiq.com/3.0/phone_intel?phone=2069735100", nil)
  	req.Header.Set("x-api-key", "YOUR_API_KEY")

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

  	body, _ := io.ReadAll(resp.Body)
  	fmt.Println(string(body))
  }
  ```

  ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
  <?php
  $curl = curl_init("https://api.trestleiq.com/3.0/phone_intel?phone=2069735100");
  curl_setopt($curl, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

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

  echo $response;
  ```

  ```java Java theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class PhoneIntelExample {
    public static void main(String[] args) throws Exception {
      HttpRequest request =
          HttpRequest.newBuilder()
              .uri(URI.create("https://api.trestleiq.com/3.0/phone_intel?phone=2069735100"))
              .header("x-api-key", "YOUR_API_KEY")
              .GET()
              .build();

      HttpResponse<String> response =
          HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
      System.out.println(response.body());
    }
  }
  ```
</CodeGroup>

## HTTP Methods

### GET (Recommended)

We recommend using GET for simplicity. Include the API key in the header:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /3.2/phone?phone=2069735100
Headers:
  x-api-key: YOUR_API_KEY
```

### POST

POST is also supported. In this case, `api_key` must be in the request body and not part of the URL:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /3.2/phone
Headers:
  Content-Type: application/json
  x-api-key: YOUR_API_KEY
Body:
{
  "phone": "2069735100",
}
```

## Security Best Practices

<Warning>
  Keep your API key secure and never expose it in client-side code or public
  repositories.
</Warning>

* Store API keys in environment variables
* Use different API keys for different environments (development, staging, production)
* Rotate API keys regularly
* Never commit API keys to version control

## Error Responses

### 400 Bad Request

* Indicates that the server cannot process the request due to client-side errors.

### 403

* **Invalid API Key**: Indicates that the API key is either incorrect or has been deactivated.
* **API Key Missing**: Indicates that your request did not include an API key.
* **API Key Expired**: Indicates that the API key has expired.

### 429 Too Many Requests

* API Key has exceeded its rate limit.

### 500 Internal Server Error

* An unexpected error occurred on the server.

## Need Help?

If you're having trouble with authentication, check our [FAQ](/guides/overview) or contact [support@trestleiq.com](mailto:support@trestleiq.com).