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

# Authentication

> How to authenticate your API requests using API keys

# Authentication

All Task Execution API endpoints require authentication. You can authenticate using either an **API key** (for server-side integrations) or a **JWT token** (for browser-based widgets).

| Method    | Format       | Use Case                                 |
| --------- | ------------ | ---------------------------------------- |
| API Key   | `sigmic_...` | Server-side integrations, scripts, CI/CD |
| JWT Token | `eyJ...`     | Browser widgets, embedded chat UIs       |

<Info>
  For browser-based integrations where code is visible to end users, use [Widget Authentication](/widget) with short-lived JWTs instead of exposing API keys.
</Info>

## API Key Authentication

### Getting Your API Key

API keys are created through the [Console](/console):

1. Log in to your Sigmic AI account
2. Open the Console and select a project
3. Go to the **API Keys** tab in project settings
4. Click **Create API Key**
5. Give your key a name and optional expiration
6. Copy and securely store the generated key

<Warning>
  The secret key is only shown once during creation. Store it securely immediately - you won't be able to see it again.
</Warning>

<Info>
  API keys are scoped to [projects](/projects). Tasks created with an API key use the configuration (MCP servers, skills, tool policies) from that key's associated project.
</Info>

### Using Your API Key

Include your API key in every request using one of these methods:

#### Option 1: Authorization Header (Recommended)

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

#### Option 2: X-API-Key Header

```bash theme={null}
X-API-Key: sigmic_your_api_key_here
```

### API Key Format

API keys follow this format:

```
sigmic_ + 64 hexadecimal characters
```

Example:

```
sigmic_3898e123bff7df20c5a60c5ce4b8b8fe316ef15cc90cb71c976eb752b8bfe7ca
```

### Example Request

```bash theme={null}
curl -X GET https://api.sigmic.ai/api/v1/tasks \
  -H "Authorization: Bearer sigmic_3898e123bff7df20c5a60c5ce4b8b8fe316ef15cc90cb71c976eb752b8bfe7ca"
```

## JWT Authentication (Widgets)

For browser-based widgets and embedded UIs, use short-lived JWT tokens instead of API keys. See the [Widget Authentication guide](/widget) for the full setup flow.

### Using a JWT

```bash theme={null}
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

JWT tokens work with all the same Task API endpoints as API keys. The auth middleware auto-detects the format based on the token prefix.

## Authentication Errors

| Error Code            | HTTP Status | Description                                        |
| --------------------- | ----------- | -------------------------------------------------- |
| `AUTH_REQUIRED`       | 401         | No authentication was provided in the request      |
| `INVALID_API_KEY`     | 401         | The API key is invalid or has expired              |
| `INVALID_AUTH_FORMAT` | 401         | Token format not recognized                        |
| `INVALID_TOKEN`       | 401         | JWT is invalid or has expired                      |
| `JWT_NOT_CONFIGURED`  | 501         | Server does not have JWT signing configured        |
| `ORIGIN_NOT_ALLOWED`  | 403         | Request origin not in widget app's allowed origins |

## Organization Context

API keys are scoped to [projects](/projects), and projects belong to an organization. When you authenticate with an API key:

* Tasks run using the project's configuration (MCP servers, skills, tool policies)
* Usage is tracked at the organization level
* Only organization members with access to the project can manage its API keys

The JWT tokens issued on login include the user's `orgId` and `orgRole` claims, which are used for authorization across all endpoints.

## Security Best Practices

<AccordionGroup>
  <Accordion title="Never expose keys in client-side code">
    API keys should only be used in server-side code. Never include them in JavaScript that runs in the browser, mobile apps, or any code that could be inspected by users.
  </Accordion>

  <Accordion title="Use environment variables">
    Store your API key in environment variables rather than hardcoding it in your source code.

    ```bash theme={null}
    export SIGMIC_API_KEY="sigmic_your_key_here"
    ```
  </Accordion>

  <Accordion title="Rotate keys periodically">
    Create new API keys periodically and disable old ones. You can manage multiple keys through the Settings panel.
  </Accordion>

  <Accordion title="Use separate keys for different environments">
    Create separate API keys for development, staging, and production environments so you can revoke them independently if needed.
  </Accordion>
</AccordionGroup>