> ## Documentation Index
> Fetch the complete documentation index at: https://badixth-dc85e378.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SemaiSens API Authentication: API Keys and Bearer Tokens

> Generate and manage API keys in your SemaiSens dashboard, then authenticate every API request using a Bearer token in the Authorization header.

Every request to the SemaiSens API must be authenticated using an API key. You generate and manage API keys directly in your account dashboard — no OAuth flow or client credentials are required. Once you have a key, include it as a Bearer token in the `Authorization` header of every request.

## Getting Your API Key

<Steps>
  <Step title="Log in to your dashboard">
    Go to [app.example.com](https://app.example.com) and sign in with your SemaiSens account credentials.
  </Step>

  <Step title="Open API Key settings">
    Navigate to **Settings → API Keys** in the left-hand navigation menu.
  </Step>

  <Step title="Create a new key">
    Click **New API Key**. Select the appropriate scope (see [Key Scopes](#key-scopes) below) and give the key a descriptive name such as `Production Integration` or `CI Pipeline`.
  </Step>

  <Step title="Copy the key immediately">
    Your API key is displayed once at creation time. Copy it now and store it somewhere secure — the dashboard will never show the full key again. If you lose it, you must generate a new one.
  </Step>
</Steps>

## Using Your API Key

Pass your API key in the `Authorization` header as a Bearer token on every request.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.example.com/v1/fields \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

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

  headers = {"Authorization": "Bearer YOUR_API_KEY"}
  response = requests.get("https://api.example.com/v1/fields", headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.example.com/v1/fields', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });
  const data = await response.json();
  ```
</CodeGroup>

<Warning>
  Never hard-code your API key in source code or commit it to a version control repository. Use environment variables (e.g., `SEMAISENS_API_KEY`) or a secrets manager to inject the key at runtime. Anyone who obtains your key can make requests on your behalf.
</Warning>

## Key Scopes

When creating a key, you assign it one of two scopes. Choose the most restrictive scope that satisfies your use case.

| Scope          | Permitted Operations                              | Recommended For                                                                                |
| -------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Read Only**  | `GET` requests only — list and retrieve resources | Dashboards, read-only reporting tools, third-party integrations that only need to display data |
| **Read/Write** | All operations — `GET`, `POST`, `PATCH`, `DELETE` | Backend services that create fields, upload imagery, trigger reports, or manage webhooks       |

<Tip>
  Use separate API keys for different environments (development, staging, production) so you can rotate or revoke keys independently without affecting other environments.
</Tip>

## Rotating Keys

To rotate a key, click **Regenerate** next to it in **Settings → API Keys**. The old key is invalidated immediately — requests using the old key will receive a `401 Unauthorized` response. Update all integrations with the new key before triggering a rotation to avoid downtime.

<Note>
  If you suspect a key has been compromised, delete it immediately from the dashboard rather than rotating it. Deletion prevents any further use of that key.
</Note>

## Authentication Error Responses

| Status             | Cause                                                                                                               | Resolution                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | The `Authorization` header is missing, malformed, or the key is invalid or deleted.                                 | Verify the header format is `Bearer YOUR_API_KEY` and that the key exists in your dashboard. |
| `403 Forbidden`    | The key is valid but its scope does not permit the requested operation (e.g., a Read Only key attempting a `POST`). | Generate a Read/Write key or adjust the scope of the existing key.                           |