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

# How to Create and Manage API Keys

> Complete guide to generate, configure, and securely manage API keys in gu1 — in the gu1 dashboard with step-by-step guidance, with examples for manage api keys.

## Interactive Tutorial

<Info>
  **Coming soon**: Interactive Clueso video will be available here. For now, follow the step-by-step guide below.
</Info>

## Overview

**API Keys** in gu1 allow you to integrate the platform with your own systems, automate workflows, and access data programmatically.

### What are API Keys?

An API Key is an **authentication credential** that identifies your application when making requests to the gu1 API. It's like a password, but designed to be used by applications instead of human users.

<Tip>
  **Security**: Treat your API keys like passwords. Never share them publicly, don't include them in versioned code (Git), and rotate them periodically.
</Tip>

## Types of API Keys

<CardGroup cols={2}>
  <Card title="Production Key" icon="building" color="#10b981">
    **For real data**

    * Accesses production data
    * Modifies real entities
    * Charges for integration usage
    * Sends webhooks to real endpoints
    * Requires maximum security
  </Card>

  <Card title="Sandbox Key" icon="flask" color="#f59e0b">
    **For development and testing**

    * Accesses sandbox data
    * Isolated environment
    * No additional cost
    * Ideal for development
    * Can be shared in dev teams
  </Card>
</CardGroup>

## Create a New API Key

<Steps>
  <Step title="Open API Keys">
    Navigate to **API Keys** at [https://app.gu1.ai/org-api-keys](https://app.gu1.ai/org-api-keys) (`/org-api-keys`).
  </Step>

  <Step title="Click 'Create API Key'">
    In the top-right corner, click the **+ Create API Key** button (blue).
  </Step>

  <Step title="Configure the API Key">
    Fill in the information:

    **Key Name**:

    * Use a descriptive name (e.g., "Integration Zapier", "Mobile App", "Data Pipeline")
    * This helps identify usage later

    **Environment**:

    * **Production**: For production applications
    * **Sandbox**: For development and testing

    **Permissions** (optional):
    By default, the key inherits permissions from your user. You can restrict:

    * **Read**: Data read-only
    * **Write**: Create and modify entities
    * **Delete**: Delete entities
    * **Execute**: Execute rules and integrations
  </Step>

  <Step title="Copy the API Key">
    <Warning>
      **IMPORTANT**: The complete API key will be shown **only once**. Copy it immediately to a safe place.
    </Warning>

    The key will have this format:

    ```
    gk_production_z1UGrahVx9NA2NG6Pj-6ZuZlFf64CEV73SpUqtt_4fflydka8MmdVAxT0cLqO3d5
    ```

    **Prefixes**:

    * `gk_production_...` - Production key
    * `gk_sandbox_...` - Sandbox key
  </Step>

  <Step title="Store Securely">
    **Recommended options**:

    * **Password manager**: 1Password, LastPass, Bitwarden
    * **Environment variables**: `.env` (don't commit to Git!)
    * **Secret managers**: AWS Secrets Manager, Google Secret Manager, HashiCorp Vault
    * **CI/CD secrets**: GitHub Secrets, GitLab CI Variables

    **❌ Never**:

    * Commit to code
    * Share via email/Slack
    * Include in screenshots
    * Leave in log files
  </Step>
</Steps>

## Use Your API Key

### HTTP Authentication

All requests must include the API key in the `Authorization` header:

```bash theme={null}
curl https://api.gu1.ai/entities \
  -H "Authorization: Bearer gk_production_YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Code Examples

<Tabs>
  <Tab title="JavaScript/Node.js">
    ```javascript theme={null}
    const GUENO_API_KEY = process.env.GUENO_API_KEY;

    // Using native fetch
    const response = await fetch('https://api.gu1.ai/entities', {
      headers: {
        'Authorization': `Bearer ${GUENO_API_KEY}`,
        'Content-Type': 'application/json'
      }
    });
    const data = await response.json();

    // Using gu1 SDK
    import { GueoClient } from '@gueno/sdk';

    const client = new GueoClient({
      apiKey: GUENO_API_KEY
    });

    const entities = await client.entities.list();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import requests

    GUENO_API_KEY = os.environ['GUENO_API_KEY']

    # Using requests
    response = requests.get(
        'https://api.gu1.ai/entities',
        headers={
            'Authorization': f'Bearer {GUENO_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    data = response.json()

    # Using gu1 SDK
    from gueno import GueoClient

    client = GueoClient(api_key=GUENO_API_KEY)
    entities = client.entities.list()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php
    $apiKey = getenv('GUENO_API_KEY');

    $ch = curl_init('https://api.gu1.ai/entities');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $data = json_decode($response, true);
    curl_close($ch);
    ?>
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'net/http'
    require 'json'

    api_key = ENV['GUENO_API_KEY']

    uri = URI('https://api.gu1.ai/entities')
    request = Net::HTTP::Get.new(uri)
    request['Authorization'] = "Bearer #{api_key}"
    request['Content-Type'] = 'application/json'

    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    data = JSON.parse(response.body)
    ```
  </Tab>
</Tabs>

## Manage Existing API Keys

### View All Keys

On the **API Keys** ([/org-api-keys](https://app.gu1.ai/org-api-keys)) page, you'll see a list of all active keys with key information like name, environment, last use, creation, and permissions.

<Info>
  **Security Note**: Only the first and last 4 characters of the key are shown (e.g., `gk_p...3d5`). The complete key cannot be retrieved.
</Info>

### Revoke an API Key

If a key was compromised or is no longer needed, you can revoke it immediately. This action is irreversible and all integrations using this key will stop working.

### Rotate an API Key

**Rotation** is the practice of periodically replacing a key for security. We recommend rotating production API keys every **90 days**.

<Tip>
  **Rotation process**: Create a new key, gradually update your systems, verify functionality, and revoke the old key.
</Tip>

## Security and Best Practices

<CardGroup cols={2}>
  <Card title="Secure Storage" icon="lock">
    Use environment variables, secret managers, and never commit keys to Git
  </Card>

  <Card title="Regular Rotation" icon="rotate">
    Production: every 90 days, immediately if compromised
  </Card>

  <Card title="Least Privilege" icon="shield-halved">
    Use minimum permissions needed for each integration
  </Card>

  <Card title="Monitoring" icon="chart-line">
    Review usage regularly and configure anomaly alerts
  </Card>
</CardGroup>

## Rate Limits and Quotas

| Plan             | Requests/min | Requests/day | Burst |
| ---------------- | ------------ | ------------ | ----- |
| **Starter**      | 60           | 10,000       | 10    |
| **Professional** | 300          | 100,000      | 50    |
| **Enterprise**   | 1,000        | Unlimited    | 200   |

The API returns limit information in `X-RateLimit-*` headers.

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/en/api-reference/authentication">
    Complete REST API documentation
  </Card>

  <Card title="Webhooks" icon="webhook" href="/en/webhooks/configuration">
    Configure real-time notifications
  </Card>

  <Card title="Integrations" icon="laptop-code" href="/en/api-reference/integrations/provider-codes">
    Integrate gu1 with third-party providers
  </Card>
</CardGroup>

## Need Help?

* **Documentation**: Browse our complete guides
* **Email**: [support@gueno.com](mailto:support@gueno.com)
* **Dashboard**: Access your account at [app.gu1.ai](https://app.gu1.ai)

***

**Last updated**: January 2025