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

# Authentication

> Learn how to authenticate with the Sterndesk API

# Authentication

All requests to the Sterndesk API require authentication using an API key. This page explains how to obtain credentials and authenticate your requests.

## Obtaining an API Key

API keys are currently issued directly by our team. To request access:

<Card title="Request API Access" icon="envelope" href="https://www.sterndesk.com/#Contact-form">
  Contact us to request your API key
</Card>

Once approved, you'll receive your API key via email. **Store this key securely.**

## Creating Additional API Keys

Within an [organization](/concepts/01-organizations-and-projects), you can create additional API keys programmatically using the API. This allows you to issue separate keys for different team members, services, or environments.

Use the `POST /api-keys` endpoint to create new keys:

```bash theme={null}
curl -X POST "https://api.sterndesk.com/r/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_...", "description": "Production service key"}'
```

See [Organizations & Projects](/concepts/01-organizations-and-projects) to learn more about managing access within your organization.

## Using Your API Key

Authenticate all API requests by including your key in the `Authorization` header using the Bearer scheme:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Example Request

```bash theme={null}
curl -X GET "https://api.sterndesk.com/r/who-am-i?echo=test" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Testing Your Authentication

Use the `/who-am-i` endpoint to verify that your API key is working correctly. This endpoint returns information about the authenticated identity.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.sterndesk.com/r/who-am-i?echo=hello" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

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

  response = requests.get(
      "https://api.sterndesk.com/r/who-am-i",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"echo": "hello"}
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.sterndesk.com/r/who-am-i?echo=hello",
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Successful Response

A successful authentication returns your identity information:

```json theme={null}
{
  "webUserAuthIdentity": "your-auth-identity",
  "numOrganizations": 1,
  "numUsers": 1,
  "mustInitializeUser": false,
  "currentUserId": "usr_abc123..."
}
```

### Error Response

If your API key is invalid or missing, you'll receive an authentication error:

```json theme={null}
{
  "code": "permission_denied",
  "message": "invalid or missing API key"
}
```

## Security Best Practices

<Warning>
  Never expose your API key in client-side code, public repositories, or logs.
</Warning>

* **Use environment variables** to store your API key
* **Rotate keys periodically** if you suspect they may have been compromised
* **Use separate keys** for development and production environments

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/get-started/03-quickstart">
    Make your first extraction request
  </Card>

  <Card title="Extraction Schemas" icon="code" href="/concepts/02-extraction-schemas">
    Define what data to extract from your documents
  </Card>
</CardGroup>