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

# FraudTrace AI API Authentication — Keys and Security

> Learn how to obtain your FraudTrace AI Bearer API key, attach it to every request, handle 401 auth errors, and keep your credentials secure in production.

Every request to the FraudTrace AI API must be authenticated with a Bearer token. There are no cookies, session handshakes, or OAuth flows — you attach a single long-lived key to the `Authorization` header and the platform handles the rest. This page explains how to get your key, use it correctly, rotate it when needed, and handle authentication errors in your integration.

## Obtain your API key

FraudTrace AI keys are issued per organisation. To request access, contact the team through [fraudtraceai.com](https://fraudtraceai.com). Once your account is provisioned you will receive a Bearer token in the format below:

```
ft_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

<Note>
  If you need a key for pre-production testing, ask for a sandbox token at the same time. Sandbox keys share the same authentication mechanism but return fixture data and do not count against your production quota.
</Note>

## Attach your key to every request

Pass your API key as a Bearer token in the `Authorization` header on every HTTP request. No other authentication mechanism is supported.

```
Authorization: Bearer YOUR_API_KEY
```

The examples below show how to do this across common HTTP clients.

<CodeGroup>
  ```bash curl theme={null}
  curl --request GET \
    --url "https://api.fraudtraceai.com/v1/verify/upi?upi=example@ybl" \
    --header "Authorization: Bearer YOUR_API_KEY"
  ```

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

  API_KEY = "YOUR_API_KEY"  # Load from environment variable in production
  BASE_URL = "https://api.fraudtraceai.com"

  headers = {
      "Authorization": f"Bearer {API_KEY}"
  }

  response = requests.get(
      f"{BASE_URL}/v1/verify/upi",
      params={"upi": "example@ybl"},
      headers=headers
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const API_KEY = process.env.FRAUDTRACE_API_KEY; // Never hard-code your key
  const BASE_URL = "https://api.fraudtraceai.com";

  const response = await fetch(
    `${BASE_URL}/v1/verify/upi?upi=example%40ybl`,
    {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
      },
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Rotate your API key

Keys do not expire automatically, but you should rotate them if you suspect a compromise or as part of your regular credential hygiene process. To request a key rotation, contact the FraudTrace support team. Your old key remains valid for a short grace period after the new key is issued, giving you time to deploy the updated secret without downtime.

## Handle authentication errors

If your request is missing the `Authorization` header, uses a malformed token, or presents a revoked key, the API returns an HTTP `401 Unauthorized` response:

```json theme={null}
{
  "error": "unauthorized",
  "message": "API key is missing or invalid."
}
```

The table below covers the most common causes and how to fix them:

| Symptom                              | Likely cause                        | Fix                                                                 |
| ------------------------------------ | ----------------------------------- | ------------------------------------------------------------------- |
| `401` on every request               | Key not included in the header      | Add `Authorization: Bearer YOUR_API_KEY` to all requests            |
| `401` after a previously working key | Key has been rotated or revoked     | Contact support to issue a new key                                  |
| `401` in production but not staging  | Different keys used per environment | Verify the correct key is loaded from your production secrets store |

<Warning>
  A `403 Forbidden` response means your key is valid but your account does not have permission to call that endpoint. This typically happens when accessing a feature (such as CyberTrace or Mobile Trace) that is not yet enabled for your plan. Contact the FraudTrace team to discuss access.
</Warning>

## Keep your key secure

Your API key grants full access to your organisation's FraudTrace account. Treat it with the same care as a database password.

* **Store it in environment variables** — use your platform's secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, or a `.env` file excluded from version control).
* **Never expose it client-side** — do not embed your key in a mobile app, browser JavaScript bundle, or any asset that end users can inspect.
* **Restrict access in your infrastructure** — only the services that need to call the FraudTrace API should have access to the key.
* **Audit usage regularly** — if you notice unexpected call volumes, rotate your key immediately and contact FraudTrace support.

<Tip>
  In Python, use the `python-dotenv` package to load `FRAUDTRACE_API_KEY` from a `.env` file during local development. In Node.js, access it via `process.env.FRAUDTRACE_API_KEY`. In production, inject the secret through your CI/CD pipeline or cloud provider's secret injection mechanism.
</Tip>