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

# Authentication

> Learn how to authenticate your API requests with Mindhunters

## Prerequisites

Before you begin, make sure you have:

* An active Mindhunters workspace account
* Access to your workspace dashboard
* Admin or developer permissions to create API tokens

## Getting Your API Token

Follow these steps to generate your API authentication token:

<Steps>
  <Step title="Log in to your Mindhunters workspace">
    Navigate to your Mindhunters workspace at `https://your-tenant.mindhunters.ai` and sign in with your credentials.
  </Step>

  <Step title="Access your profile">
    Click on your profile icon in the top right corner of the dashboard.
  </Step>

  <Step title="Navigate to Developer section">
    From the dropdown menu, select **"Developer"** to access the developer settings.
  </Step>

  <Step title="Create a new API token">
    In the Developer section:

    * Click on **"Create New API Token"** or **"Generate Token"**
    * Give your token a descriptive name (e.g., "Production API", "Development Testing")
    * Set appropriate permissions if prompted
    * Click **"Create"** or **"Generate"**
  </Step>

  <Step title="Copy and secure your token">
    **Important**: Copy your API token immediately and store it securely. For security reasons, you won't be able to see it again after closing the dialog.

    Store your token in a secure location such as:

    * Environment variables
    * Secure credential management systems
    * Password managers (for development)
  </Step>
</Steps>

<Warning>
  **Never share your API token** or commit it to version control systems. Treat it like a password. If you suspect your token has been compromised, revoke it immediately and generate a new one.
</Warning>

## Understanding Your Tenant/Subdomain

Your Mindhunters workspace URL contains your **tenant identifier** (also called subdomain), which is required for all API calls.

### How to Find Your Tenant

Your tenant is the subdomain in your Mindhunters workspace URL:

```
https://abc.mindhunters.ai
         ^^^
      This is your tenant
```

If your workspace URL is `https://abc.mindhunters.ai`, then your tenant is `abc`.

### Using Your Tenant in API Calls

All API endpoints use your tenant in the base URL:

```
https://{your-tenant}.mindhunters.ai/api/v1/...
```

**Example:**

```
https://abc.mindhunters.ai/api/v1/calls
```

## Authentication Format

Mindhunters API uses **Bearer Token Authentication**. Include your API token in the `Authorization` header of every request:

```
Authorization: Bearer YOUR_API_TOKEN
```

### Example Authentication Headers

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://abc.mindhunters.ai/api/v1/calls \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://abc.mindhunters.ai/api/v1/calls', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  ```

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

  url = "https://abc.mindhunters.ai/api/v1/calls"
  headers = {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json"
  }

  response = requests.get(url, headers=headers)
  data = response.json()
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const response = await axios.get('https://abc.mindhunters.ai/api/v1/calls', {
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    }
  });

  const data = response.data;
  ```
</CodeGroup>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store tokens securely">
    * Use environment variables for API tokens
    * Never hardcode tokens in your source code
    * Use secure credential management systems in production
    * Rotate tokens periodically
  </Accordion>

  <Accordion title="Use HTTPS only">
    All API requests must use HTTPS. HTTP requests will be rejected. The Mindhunters API enforces TLS 1.2 or higher.
  </Accordion>

  <Accordion title="Implement token rotation">
    * Create multiple tokens for different services
    * Rotate tokens regularly (every 90 days recommended)
    * Have a process to quickly rotate compromised tokens
  </Accordion>

  <Accordion title="Limit token scope">
    * Create separate tokens for different environments (development, staging, production)
    * Use descriptive names to track token usage
    * Revoke unused tokens immediately
  </Accordion>

  <Accordion title="Monitor token usage">
    * Regularly review API logs for unusual activity
    * Set up alerts for failed authentication attempts
    * Monitor token usage in the Developer section of your dashboard
  </Accordion>
</AccordionGroup>

## Token Management

### Viewing Active Tokens

You can view all active API tokens in the Developer section of your workspace:

1. Go to your profile → Developer
2. View the list of active tokens
3. See token creation date and last used timestamp

### Revoking Tokens

If you need to revoke a token:

1. Navigate to Developer section
2. Find the token in your list
3. Click **"Revoke"** or the delete icon
4. Confirm the revocation

<Warning>
  Revoking a token immediately invalidates it. Any applications using that token will no longer be able to authenticate.
</Warning>

### Creating Multiple Tokens

You can create multiple tokens for different purposes:

* **Development**: For local testing and development
* **Staging**: For staging environment deployments
* **Production**: For production applications
* **CI/CD**: For automated deployment pipelines

## Authentication Errors

Common authentication errors and how to resolve them:

| Status Code | Error                        | Solution                                                |
| ----------- | ---------------------------- | ------------------------------------------------------- |
| 401         | Unauthorized                 | Verify your token is correct and hasn't been revoked    |
| 401         | Missing Authorization header | Include the `Authorization: Bearer YOUR_TOKEN` header   |
| 401         | Invalid token format         | Ensure you're using `Bearer YOUR_TOKEN` format          |
| 403         | Forbidden                    | Check that your token has the necessary permissions     |
| 404         | Not Found                    | Verify your tenant/subdomain in the base URL is correct |

## Testing Your Authentication

You can test your authentication by making a simple API call:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://your-tenant.mindhunters.ai/api/v1/calls \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const testAuth = async () => {
    try {
      const response = await fetch('https://your-tenant.mindhunters.ai/api/v1/calls', {
        headers: {
          'Authorization': 'Bearer YOUR_API_TOKEN',
          'Content-Type': 'application/json'
        }
      });

      if (response.ok) {
        console.log('Authentication successful!');
      } else {
        console.error('Authentication failed:', response.status);
      }
    } catch (error) {
      console.error('Error:', error);
    }
  };

  testAuth();
  ```

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

  def test_auth():
      url = "https://your-tenant.mindhunters.ai/api/v1/calls"
      headers = {
          "Authorization": "Bearer YOUR_API_TOKEN",
          "Content-Type": "application/json"
      }

      try:
          response = requests.get(url, headers=headers)
          if response.status_code == 200:
              print("Authentication successful!")
          else:
              print(f"Authentication failed: {response.status_code}")
      except Exception as e:
          print(f"Error: {e}")

  test_auth()
  ```
</CodeGroup>

## Next Steps

Now that you have your API token and understand authentication:

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Make your first API call
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore all available endpoints
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Set up real-time notifications
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/monitoring">
    Track your API usage
  </Card>
</CardGroup>