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

# Authentication

> Authenticate your API requests with API keys

# Authentication

All requests to the Gomry API must include a valid API key. API keys are scoped to your **organization** and gated by a per-resource **scope map** that controls which resources the key can read or write. See [Scopes](/scopes) for the full list and how to configure them.

## Generating an API Key

1. Log in to your [Gomry dashboard](https://www.gomry.com)
2. Navigate to **Organization Settings → API Keys**
3. Click **Create API Key** and give it a descriptive name
4. Copy the key immediately — **it is only displayed once**

<Warning>
  Treat your API key like a password. Anyone with your key can read your organization's event data. Never commit it to version control or expose it in client-side code.
</Warning>

## Using Your API Key

Include the key in the `X-API-KEY` header on every request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-KEY: your_api_key_here" \
    https://www.gomry.com/api/v1/events/YOUR_EVENT_ID
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://www.gomry.com/api/v1/events/YOUR_EVENT_ID",
    {
      headers: {
        "X-API-KEY": "your_api_key_here",
      },
    }
  );
  const { data } = await response.json();
  ```

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

  response = requests.get(
      "https://www.gomry.com/api/v1/events/YOUR_EVENT_ID",
      headers={"X-API-KEY": "your_api_key_here"},
  )
  data = response.json()["data"]
  ```
</CodeGroup>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store keys in environment variables">
    Never hardcode API keys in your source code. Use environment variables or a secrets manager.

    ```bash theme={null}
    export GOMRY_API_KEY="your_api_key_here"
    ```
  </Accordion>

  <Accordion title="Use server-side requests only">
    API keys should only be used in server-side code. Never include them in frontend JavaScript, mobile apps, or any code that runs on user devices.
  </Accordion>

  <Accordion title="Rotate keys periodically">
    Create a new key and revoke the old one periodically. You can manage keys in your dashboard under **Organization Settings → API Keys**.
  </Accordion>

  <Accordion title="Use separate keys for each integration">
    Create a dedicated key for each integration or service. This way, if a key is compromised, you can revoke it without affecting other integrations.
  </Accordion>
</AccordionGroup>

## Authentication Errors

| Status | Error                        | Meaning                                                                                 |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------- |
| `401`  | `Missing X-API-KEY header`   | No API key was provided in the request                                                  |
| `401`  | `Invalid or revoked API key` | The key doesn't exist or has been revoked                                               |
| `403`  | `insufficient_scope`         | The key is valid but lacks the required scope for this resource (see [Scopes](/scopes)) |