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

# Authentication

> How to authenticate with the Giza API

## Overview

The Giza API uses API key authentication. Authenticated endpoints require two headers on each request.

## Required Headers

```bash theme={null}
X-Partner-API-Key: your-api-key
X-Partner-Name: your-partner-name
```

### Example Request

```bash theme={null}
curl -X POST "https://partners-backend-1038109371738.europe-west1.run.app/api/v1/8453/wallets" \
  -H "Content-Type: application/json" \
  -H "X-Partner-API-Key: your-api-key" \
  -H "X-Partner-Name: your-partner-name" \
  -d '{
    "wallet": "0x1234567890abcdef1234567890abcdef12345678",
    "eoa": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "initial_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "selected_protocols": ["aave", "compound", "moonwell"]
  }'
```

## Obtaining API Credentials

<Steps>
  <Step title="Contact Giza">
    Reach out to the Giza team to request partner access.

    <Card title="Request Access" icon="envelope" href="https://www.gizatech.xyz/">
      Visit gizatech.xyz to get started
    </Card>
  </Step>

  <Step title="Receive Credentials">
    You'll receive:

    * **API Key**: A unique key for authentication
    * **Partner Name**: Your registered partner identifier
    * **Backend URL**: The API endpoint URL
  </Step>

  <Step title="Configure Environment">
    Store credentials securely as environment variables:

    ```bash .env theme={null}
    GIZA_API_KEY=your-api-key
    GIZA_PARTNER_NAME=your-partner-name
    GIZA_API_URL=https://partners-backend-1038109371738.europe-west1.run.app
    ```
  </Step>
</Steps>

## Authentication Scopes

Different endpoints require different authentication levels:

### Public Endpoints (No Auth Required)

These endpoints can be called without authentication:

| Endpoint                                   | Description                        |
| ------------------------------------------ | ---------------------------------- |
| `GET /api/v1/healthcheck`                  | Health check                       |
| `GET /api/v1/chains`                       | List supported chains              |
| `GET /api/v1/{chain_id}/tokens`            | List supported tokens              |
| `GET /api/v1/{chain_id}/{token}/protocols` | Get protocol information           |
| `GET /api/v1/{chain_id}/wallets/{wallet}`  | Get wallet information (read-only) |
| `GET /api/v1/{chain_id}/stats`             | Get statistics                     |

### Authenticated Endpoints

These endpoints require API key authentication:

| Endpoint                                                 | Description         |
| -------------------------------------------------------- | ------------------- |
| `POST /api/v1/{chain_id}/wallets`                        | Activate wallet     |
| `POST /api/v1/{chain_id}/wallets/{wallet}:deactivate`    | Deactivate wallet   |
| `POST /api/v1/{chain_id}/wallets/{wallet}:withdraw`      | Withdraw funds      |
| `POST /api/v1/{chain_id}/wallets/{wallet}:run`           | Trigger agent run   |
| `POST /api/v1/{chain_id}/wallets/{wallet}:top-up`        | Top up wallet       |
| `POST /api/v1/{chain_id}/wallets/{wallet}:claim-rewards` | Claim rewards       |
| `PUT /api/v1/{chain_id}/wallets/{wallet}/protocols`      | Update protocols    |
| `POST /api/v1/optimizer/{chain_id}/optimize`             | Optimize allocation |

## Error Responses

### Invalid or Missing API Key

```json theme={null}
{
  "detail": "Invalid or missing API key"
}
```

**HTTP Status**: `401 Unauthorized`

### Access Denied

```json theme={null}
{
  "detail": "Access denied"
}
```

**HTTP Status**: `403 Forbidden`

This occurs when:

* Trying to access another partner's wallet
* API key is inactive
* Partner doesn't have permission for the operation

## Security Best Practices

<Warning>
  **Never expose your API key in client-side code!** Always make API calls from your backend server.
</Warning>

<AccordionGroup>
  <Accordion title="Store credentials securely">
    * Use environment variables, not hardcoded strings
    * Never commit `.env` files to version control
    * Use a secrets manager in production (AWS Secrets Manager, HashiCorp Vault, etc.)
  </Accordion>

  <Accordion title="Rotate keys periodically">
    Contact Giza to regenerate your API key if:

    * You suspect it's been compromised
    * An employee with access leaves your organization
    * As part of regular security hygiene
  </Accordion>

  <Accordion title="Use HTTPS only">
    Always use HTTPS when making API requests. Never send API keys over unencrypted connections.
  </Accordion>

  <Accordion title="Implement server-side calls">
    Make all authenticated API calls from your backend:

    ```typescript theme={null}
    // ✅ Good: Server-side API call
    // pages/api/activate.ts (Next.js)
    export default async function handler(req, res) {
      const response = await fetch('https://api.giza.../wallets', {
        headers: {
          'X-Partner-API-Key': process.env.GIZA_API_KEY,
          'X-Partner-Name': process.env.GIZA_PARTNER_NAME,
        },
        body: req.body,
      });
      res.json(await response.json());
    }

    // ❌ Bad: Client-side API call (exposes key!)
    // Don't do this in frontend code
    fetch('https://api.giza.../wallets', {
      headers: {
        'X-Partner-API-Key': 'exposed-key', // NEVER DO THIS
      },
    });
    ```
  </Accordion>
</AccordionGroup>

## Using with the SDK

The [TypeScript SDK](/sdk-reference/overview) handles authentication automatically:

```typescript theme={null}
import { Giza, Chain } from '@gizatech/agent-sdk';

// SDK reads from environment variables:
// - GIZA_API_KEY
// - GIZA_PARTNER_NAME
// - GIZA_API_URL

const giza = new Giza({
  chain: Chain.BASE,
});

// Authentication headers are added automatically
const agent = await giza.createAgent('0x...');
await agent.activate({...});
```

<Card title="SDK Overview" icon="code" href="/sdk-reference/overview">
  We recommend using the SDK for simplified authentication
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Activate Wallet" icon="rocket" href="/api-reference/agents/activate-wallet">
    Create your first agent
  </Card>

  <Card title="Get Protocols" icon="layer-group" href="/api-reference/protocols/get-protocols">
    Discover available protocols
  </Card>
</CardGroup>