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

# SURCHI API Authentication: API Keys and Bearer Tokens

> All SURCHI API requests require an API key passed as a Bearer token in the Authorization header. Learn how to create, scope, and rotate your API keys.

Every request to the SURCHI API must be authenticated with an API key passed as a Bearer token in the `Authorization` header. API keys are tied to your account, carry specific permission scopes, and are the primary mechanism for tracking and enforcing your plan's rate limits. There are no public endpoints — even read-only queries require a valid key.

## Getting an API Key

<Steps>
  <Step title="Sign in to your dashboard">
    Go to [surchi.xyz/dashboard](https://surchi.xyz/dashboard) and sign in with your account credentials.
  </Step>

  <Step title="Navigate to API Keys">
    Open the left sidebar and click **Settings**, then select **API Keys** from the settings menu.
  </Step>

  <Step title="Click &#x22;Create New Key&#x22;">
    Click the **Create New Key** button in the top-right corner of the API Keys page.
  </Step>

  <Step title="Name your key and choose its scope">
    Give the key a descriptive name (e.g. `prod-trading-bot` or `dev-portfolio-app`) so you can identify it later. Select the minimum set of scopes your application needs. See the [Key Scopes](#key-scopes) table below for available options.
  </Step>

  <Step title="Copy the key immediately">
    After creation, your full API key is displayed **exactly once**. Copy it now and store it in a secure secrets manager or environment variable. If you lose it, you will need to revoke the key and create a new one.
  </Step>
</Steps>

## Using Your API Key

Pass your API key in the `Authorization` header using the `Bearer` scheme on every request. The header must be formatted exactly as shown — including the `Bearer ` prefix followed by a single space.

```
Authorization: Bearer sk_live_xxxxxxxxxxxx
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
    https://api.surchi.xyz/v1/trending
  ```

  ```typescript TypeScript theme={null}
  const SURCHI_API_KEY = process.env.SURCHI_API_KEY;

  const headers = {
    'Authorization': `Bearer ${SURCHI_API_KEY}`,
    'Content-Type': 'application/json'
  };

  const response = await fetch('https://api.surchi.xyz/v1/trending', { headers });
  const data = await response.json();
  ```

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

  headers = {
      'Authorization': f'Bearer {os.environ["SURCHI_API_KEY"]}',
      'Content-Type': 'application/json'
  }

  response = requests.get('https://api.surchi.xyz/v1/trending', headers=headers)
  print(response.json())
  ```

  ```go Go theme={null}
  import (
      "net/http"
      "os"
  )

  req, _ := http.NewRequest("GET", "https://api.surchi.xyz/v1/trending", nil)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("SURCHI_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  ```

  ```rust Rust theme={null}
  use reqwest::Client;

  let api_key = std::env::var("SURCHI_API_KEY").expect("SURCHI_API_KEY not set");
  let client = Client::new();

  let response = client
      .get("https://api.surchi.xyz/v1/trending")
      .header("Authorization", format!("Bearer {}", api_key))
      .send()
      .await?;
  ```
</CodeGroup>

## Key Scopes

When you create an API key, you assign it one or more scopes that define what it is allowed to do. Use the narrowest set of scopes your application actually requires — this limits the blast radius if a key is ever exposed.

| Scope            | Description                        |
| ---------------- | ---------------------------------- |
| `read:tokens`    | Read token data and analytics      |
| `read:wallets`   | Read wallet data and PnL           |
| `read:contracts` | Run AI contract audits             |
| `read:liquidity` | Access liquidity and routing data  |
| `write:alerts`   | Create and manage alerts           |
| `full`           | All permissions (use with caution) |

<Tip>
  For most read-only integrations, you only need `read:tokens` and `read:wallets`. Avoid the `full` scope unless your application genuinely requires write access alongside all read permissions.
</Tip>

## Key Rotation

You should rotate your API keys periodically and immediately after any suspected exposure. To rotate a key:

1. Create a new key with the same scopes as the one you are replacing.
2. Deploy the new key to your application and verify it works correctly.
3. Revoke the old key from the **Settings → API Keys** dashboard.

<Warning>
  Revoking a key takes effect immediately and is irreversible. Any application still using the old key will begin receiving `401 Unauthorized` errors the moment you revoke it. Always confirm your new key is fully deployed and operational before revoking the old one.
</Warning>

## Security Best Practices

Keeping your API keys secure is your responsibility. Follow these practices to minimise risk:

* **Use environment variables.** Never hard-code API keys in your source code. Load them at runtime from environment variables or a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or Doppler.
* **Never commit keys to source control.** Add a `.env` file (or whichever file holds your secrets) to `.gitignore`. Scan your repository history if you suspect a key was ever committed, and rotate it immediately.
* **Use narrow scopes.** Issue separate keys for separate applications, each with only the scopes it needs. A compromised read-only key cannot be used to create or destroy alerts.
* **Monitor key usage.** The SURCHI dashboard shows per-key request volume and error rates. Unusual spikes may indicate your key has been shared or leaked.
* **Rotate keys regularly.** Even without a known incident, rotating keys every 90 days is a sound practice for production applications.

## Authentication Errors

If your key is missing, malformed, or has been revoked, the API returns HTTP `401`. If your key is valid but lacks the required scope for the endpoint you called, it returns HTTP `403`.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "status": 401
  }
}
```

```json theme={null}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Your API key does not have the required scope for this endpoint",
    "status": 403
  }
}
```

See the [Errors](/developer/api/errors) reference for the full list of error codes and troubleshooting guidance.