# API Keys

API keys let you authenticate against the GoSmarter API without an OAuth login flow. They are ideal for scripts, CI/CD pipelines, and server-to-server integrations.

## Overview

Each API key is tied to the user account that created it and carries that user's company memberships and roles at creation time. The gateway reads this metadata on every request to enforce the same permissions as your interactive session.

## Getting a Key

Log in to this developer portal → **My Account → API Keys → Create key**. Copy the value — it is only shown once.

## Using a Key

Pass the key in the `GoSmarter-Api-Key` request header:

```http
GET /api/company/{companyId}/millcert/certificates
GoSmarter-Api-Key: zpka_your_key_here
```

### curl

```bash
curl "https://api.gosmarter.ai/api/company/YOUR_COMPANY_ID/millcert/certificates" \
  -H "GoSmarter-Api-Key: $GOSMARTER_API_KEY"
```

### JavaScript / Node.js

```javascript
const response = await fetch(
  "https://api.gosmarter.ai/api/company/YOUR_COMPANY_ID/millcert/certificates",
  {
    headers: {
      "GoSmarter-Api-Key": process.env.GOSMARTER_API_KEY,
    },
  }
);
const data = await response.json();
```

### Python

```python
import requests, os

resp = requests.get(
    "https://api.gosmarter.ai/api/company/YOUR_COMPANY_ID/millcert/certificates",
    headers={"GoSmarter-Api-Key": os.environ["GOSMARTER_API_KEY"]},
)
resp.raise_for_status()
data = resp.json()
```

## Rolling a Key

Rolling replaces your key in one step — a new key is issued and all old keys for your account are deleted. Use this to rotate credentials without downtime.

Go to **My Account → API Keys → Roll** in this portal, or call the endpoint directly (requires a Bearer token):

```bash
curl -X POST "https://api.gosmarter.ai/api/me/keys/roll" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

Update any scripts or secrets managers with the new key before the old one stops working.

## Revoking a Key

Delete a key immediately from **My Account → API Keys → Delete**. The key stops working instantly.

## Permissions

Keys carry your company memberships and roles **at the time the key was created**. If your permissions change after creation (for example, you are added to a new company), delete and recreate your key to pick up the updated permissions.

:::info

Rolling a key does not refresh your permissions snapshot — only creating a new key does.

:::

## Security

- Store keys in environment variables or a secrets manager — never in source code.
- Delete keys that are no longer needed.
- A compromised key should be deleted immediately.

:::warning

**Never commit an API key to version control.** If a key is accidentally exposed, delete it immediately from **My Account → API Keys** and create a replacement.

:::