> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiandgpu.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

AGCloud API uses Bearer token authentication. All API requests must include your API key in the Authorization header.

### Get Your API Key

1. Sign up for a AGCloud account at [**Dashboard**](https://developer.aiandgpu.com)
2. Navigate to the API Keys section in your Dashboard
3. Generate a new API key
4. Copy and securely store your API key

<Warning>
  **Keep Your API Key Secure**

  * Never commit API keys to version control
  * Don’t share your API key publicly
  * Use environment variables to store keys
  * Rotate keys regularly for enhanced security
</Warning>

## Making Authenticated Requests

Include your API key in the `Authorization` header with the `Bearer` prefix:

<CodeGroup>
  ```shellscript cURL theme={null}
  curl https://aiandgpu.com/v1/messages \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
     "model": "claude-haiku-4-5-20251001",
      "messages": [
          {
              "role":"user",
              "content": [{"type":"text","text": "Hello!"}]
          }
      ]
    }'
  ```
</CodeGroup>

## Envitonment Variables

### Recommended Setup

Store your `API key` in environment variables instead of hardcoding it:

<CodeGroup>
  ```shellscript Linux/macOS theme={null}
  export AGCLOUD_API_KEY="<YOUR_API_KEY>"
  ```

  ```shellscript Windows PowerShell theme={null}
  $env:AGCLOUD_API_KEY="<YOUR_API_KEY>"
  ```

  ```shellscript .env File theme={null}
  AGCLOUD_API_KEY=<YOUR_API_KEY>
  ```
</CodeGroup>

### Using .env Files

For local development, use a `.env` file:

<CodeGroup>
  ```python Python theme={null}
  # Install python-dotenv
  from dotenv import load_dotenv
  import os

  load_dotenv()
  api_key = os.getenv("AGCLOUD_API_KEY")
  ```

  ```javascript Node.js theme={null}
  // Install dotenv
  require('dotenv').config();
  const apiKey = process.env.AGCLOUD_API_KEY;
  ```

  ```go Go theme={null}
  // Install godotenv
  // https://github.com/joho/godotenv
  import "os"
  var apiKey = os.Getenv("AGCLOUD_API_KEY")
  ```

  ```java Java theme={null}
  // Install dotenv-java (recommended)
  // https://github.com/cdimascio/dotenv-java
  import io.github.cdimascio.dotenv.Dotenv;

  Dotenv dotenv = Dotenv.configure().ignoreIfMissing().load();
  String apiKey = dotenv.get("AGCLOUD_API_KEY");
  ```

  ```php PHP theme={null}
  // composer require vlucas/phpdotenv (recommended)
  require __DIR__ . '/vendor/autoload.php';

  $dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
  $dotenv->safeLoad();
  $apiKey = $_ENV['AGCLOUD_API_KEY'] ?? null;
  ```

  ```csharp C# theme={null}
  // dotnet add package DotNetEnv (recommended)
  using System;
  using DotNetEnv;

  Env.Load();
  var apiKey = Environment.GetEnvironmentVariable("AGCLOUD_API_KEY");
  ```
</CodeGroup>

<Note>
  Important! Remember add `.env` to your `.gitignore` file to prevent accidentally committing secrets.
</Note>

## Authentication Errors

### Common Error Responses(Claude Code)

<ParamField query="400 Invalid Request" type="error">
  The request body is malformed or contains invalid parameters. Common causes include: missing required fields (e.g. `model`, `messages`, `max_tokens`), incorrect data types, invalid JSON syntax, or unsupported parameter values. Please review your request payload and ensure it conforms to the API specification.

  ```json theme={null}
  {
      "type": "error",
      "error": {
        "type": "invalid_request_error",
        "message": "Invalid request error"
      }
  }
  ```
</ParamField>

<ParamField query="401 Unauthorized" type="error">
  Authentication failed. This typically occurs when the API key is missing from the `Authorization` header, the key format is incorrect, or the key has been revoked or expired. Ensure your request includes a valid API key in the header as `Authorization: <YOUR_API_KEY>`.

  ```json theme={null}
  {
      "type": "error",
      "error": {
        "type": "authentication_error",
        "message": "Authentication error"
      }
  }
  ```
</ParamField>

<ParamField query="402 Insufficient Balance" type="error">
  Your account balance is not enough to process this request. API calls are charged based on token usage, and your current balance cannot cover the cost. Please top up your account at the [**Dashboard**](https://developer.aiandgpu.com) before continuing to use the service.

  ```json theme={null}
  {
      "type": "error",
      "error": {
        "type": "insufficient_balance",
        "message": "Your current account balance is insufficient"
      }
  }
  ```
</ParamField>

<ParamField query="403 Permission Denied" type="error">
  Your account has exceeded its allocated usage quota. This may be a daily, monthly, or total usage limit depending on your plan. Please check your current quota and usage in the [**Dashboard**](https://developer.aiandgpu.com), or contact support to upgrade your plan.

  ```json theme={null}
  {
      "type": "error",
      "error": {
        "type": "quota_exceeded",
        "message": "Quota exceeded"
      }
  }
  ```
</ParamField>

<ParamField query="429 Too Many Requests" type="error">
  Too many requests in a short period of time. The API enforces rate limits to ensure fair usage and service stability. Please wait a moment and retry your request. We recommend implementing exponential backoff in your client to handle rate limiting gracefully.

  ```json theme={null}
  {
      "type": "error",
      "error": {
        "type": "rate_limit_error",
        "message": "Rate limit exceeded"
      }
  }
  ```
</ParamField>

<ParamField query="500 Internal Server Error" type="error">
  The server encountered an unexpected condition that prevented it from fulfilling the request. Please try again later or contact support if the problem persists.

  ```json theme={null}
  {
      "type": "error",
      "error": {
        "type": "internal_server_error",
        "message": "Internal server error"
      }
  }
  ```
</ParamField>

## Best Practices

<AccordionGroup>
  <Accordion icon="book-open" title="Use Environment Variables">
    Always store API keys in environment variables, never in your source code
  </Accordion>

  <Accordion icon="rotate-exclamation" title="implement-key-rotation">
    Regularly rotate your API keys to minimize security risks. Generate new keys and update your applications before revoking old ones.
  </Accordion>

  <Accordion icon="code-pull-request-closed" title="Use Different Keys for Different Environments">
    Use sepatate API Keys for development, staging, and production environments.
  </Accordion>

  <Accordion icon="monitor-waveform" title="Monitor API KeyUsage">
    Regularly check your API usage in dashboard to detect any on rasks.
  </Accordion>

  <Accordion icon="hourglass-start" title="Implement Rate Limiting">
    Implement client-side rate limiting to avoid hitting API rate limits
  </Accordion>
</AccordionGroup>

## API Key Management

### Generating New Keys

1. Log in to your [**Dashboard**](https://developer.aiandgpu.com)
2. Navigate to **API Keys**
3. Click **Generate New Key**
4. Give your key a descriptive name
5. Copy the key immediately (you won’t be able to see it again)

### Revoking Your API Keys

If you suspect your API key has been compromised:

1. Go to your [**Dashboard**](https://developer.aiandgpu.com)
2. Find the compromised key in the API Keys section
3. Click **Revoke**
4. Generate a new key and update your applications

<Tip>
  Set up key expiration policies to automatically rotate keys after a specified period.
</Tip>

## Customer Support

If you’re experiencing authentication issues:

* Check that your API key is correctly formatted
* Verify your key hasn’t been revoked
* Ensure you’re using the correct API endpoint
* Contact \[[info@thousandcloud.com](mailto:info@thousandcloud.com)]for help