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

# Authentication

> Secure your API requests with API keys

# Authentication

All API requests require authentication via an API key. Keys are scoped to your account and can be managed from your dashboard.

## Creating an API Key

### From the Dashboard

1. Go to **Settings → API Keys**
2. Click **Create New Key**
3. Give it a name (e.g., "Production", "Development")
4. Copy the key immediately — **it won't be shown again**

### Via API

```bash theme={}
# Create a key (requires session auth)
curl -X POST https://garmint.app/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{ "name": "My Integration" }'
```

Response:

```json theme={}
{
  "key": "gm_live_a1b2c3d4e5f6...",
  "metadata": {
    "id": "key_xxx",
    "name": "My Integration",
    "lastFour": "f6g7",
    "createdAt": "2024-12-19T12:00:00Z"
  },
  "warning": "Save this key now - it will not be shown again!"
}
```

## Using Your API Key

Include your API key in the `Authorization` header:

```bash theme={}
curl https://garmint.app/api/v1/garments \
  -H "Authorization: Bearer gm_live_xxx"
```

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

## Key Format

Keys follow this format:

```
gm_live_<64 character hex string>
```

* `gm_` — Garmint prefix
* `live_` — Environment (live for production)
* `<hex>` — Unique identifier

## Key Security Best Practices

<AccordionGroup>
  <Accordion title="Store keys securely">
    Use environment variables or a secrets manager. Never commit keys to git.

    ```bash theme={}
    # .env.local (gitignored)
    GARMINT_API_KEY=gm_live_xxx
    ```
  </Accordion>

  <Accordion title="Use separate keys per environment">
    Create different keys for development, staging, and production. This lets you rotate keys independently.
  </Accordion>

  <Accordion title="Set expiration dates">
    When creating keys, consider setting an expiration:

    ```json theme={}
    { "name": "Temp Integration", "expiresInDays": 30 }
    ```
  </Accordion>

  <Accordion title="Revoke compromised keys immediately">
    If a key is exposed, revoke it from the dashboard or via API:

    ```bash theme={}
    curl -X DELETE https://garmint.app/api/v1/keys/key_xxx
    ```
  </Accordion>
</AccordionGroup>

## Managing Keys

### List All Keys

```bash theme={}
curl https://garmint.app/api/v1/keys \
  -H "Cookie: <session>"
```

### Revoke a Key

```bash theme={}
# Revoke (soft delete - key stops working)
curl -X DELETE https://garmint.app/api/v1/keys/key_xxx

# Permanent delete
curl -X DELETE "https://garmint.app/api/v1/keys/key_xxx?permanent=true"
```

## Error Responses

### Invalid or Missing Key

```json theme={}
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key. Provide a valid key via Authorization header."
  }
}
```

Status: `401 Unauthorized`

### Revoked Key

```json theme={}
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key. Provide a valid key via Authorization header.",
    "details": { "reason": "API key has been revoked" }
  }
}
```

Status: `401 Unauthorized`

### Expired Key

```json theme={}
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key. Provide a valid key via Authorization header.",
    "details": { "reason": "API key has expired" }
  }
}
```

Status: `401 Unauthorized`