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

# Authentication

> Secure your API requests with proper authentication

## Overview

The HirePanda API uses API keys to authenticate requests. API keys are associated with your workspace and can be managed from your dashboard.

<Warning>
  API keys are sensitive credentials. Never expose them in client-side code, commit them to version control, or share them publicly.
</Warning>

## Getting Your API Key

<Steps>
  <Step title="Navigate to Settings">
    Go to your [Dashboard Settings](https://valley.hirepanda.com/settings)
  </Step>

  <Step title="Select API Keys">
    Click on "API Keys" in the settings menu
  </Step>

  <Step title="Generate New Key">
    Click "Generate New API Key" and provide a descriptive name
  </Step>

  <Step title="Copy and Secure">
    Copy the key immediately - it won't be shown again
  </Step>
</Steps>

## Using Your API Key

### Header Authentication

Include your API key in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.hirepanda.com/api/v1/jobs
```

### Example Requests

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://api.hirepanda.com/api/v1/jobs', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });
  ```

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

  response = requests.get(
      'https://api.hirepanda.com/api/v1/jobs',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      }
  )
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'uri'

  uri = URI.parse("https://api.hirepanda.com/api/v1/jobs")
  request = Net::HTTP::Get.new(uri)
  request["Authorization"] = "Bearer YOUR_API_KEY"
  request["Content-Type"] = "application/json"

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end
  ```

  ```php PHP theme={null}
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://api.hirepanda.com/api/v1/jobs");
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer YOUR_API_KEY",
      "Content-Type: application/json"
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  curl_close($ch);
  ```
</CodeGroup>

## API Key Management

### Key Permissions

Configure granular permissions for each API key:

<Tabs>
  <Tab title="Read Only">
    * View jobs
    * List candidates
    * Access analytics
    * Read webhooks
  </Tab>

  <Tab title="Write Access">
    * All read permissions
    * Create/update jobs
    * Manage candidates
    * Configure webhooks
  </Tab>

  <Tab title="Admin Access">
    * All permissions
    * Manage team members
    * Access billing
    * Delete resources
  </Tab>
</Tabs>

### Key Rotation

Best practices for key security:

<AccordionGroup>
  <Accordion title="Regular Rotation">
    Rotate API keys every 90 days to minimize exposure risk

    ```bash theme={null}
    # 1. Generate new key
    # 2. Update your applications
    # 3. Test new key
    # 4. Revoke old key
    ```
  </Accordion>

  <Accordion title="Emergency Rotation">
    If a key is compromised:

    1. Immediately revoke the compromised key
    2. Generate a new key
    3. Update all applications
    4. Review API logs for unauthorized access
  </Accordion>
</AccordionGroup>

### Multiple Keys

Use different keys for different purposes:

| Key Type    | Use Case          | Permissions    |
| ----------- | ----------------- | -------------- |
| Production  | Live application  | Full access    |
| Development | Local development | Limited access |
| CI/CD       | Automated testing | Read only      |
| Analytics   | Reporting tools   | Analytics only |

## Security Best Practices

### Environment Variables

Store API keys in environment variables:

<CodeGroup>
  ```bash .env theme={null}
  HIREPANDA_API_KEY=your_api_key_here
  ```

  ```javascript Node.js theme={null}
  const apiKey = process.env.HIREPANDA_API_KEY;
  ```

  ```python Python theme={null}
  import os
  api_key = os.environ.get('HIREPANDA_API_KEY')
  ```
</CodeGroup>

### Secure Storage

<CardGroup cols={2}>
  <Card title="Do's" icon="check">
    * Use environment variables
    * Use secret management tools
    * Encrypt keys at rest
    * Limit key permissions
  </Card>

  <Card title="Don'ts" icon="xmark">
    * Hard-code in source code
    * Commit to version control
    * Share in documentation
    * Use in client-side code
  </Card>
</CardGroup>

## OAuth 2.0 (Coming Soon)

We're implementing OAuth 2.0 for more secure, user-centric authentication:

### Planned Features

* Authorization code flow
* Refresh tokens
* Scope-based permissions
* Third-party app support

<Info>
  OAuth 2.0 support is planned for Q2 2024. Contact [sales@hirepanda.com](mailto:sales@hirepanda.com) for early access.
</Info>

## IP Whitelisting

For additional security, restrict API access by IP:

<Steps>
  <Step title="Enable IP Whitelisting">
    Go to Settings → Security → IP Whitelist
  </Step>

  <Step title="Add IP Addresses">
    Add your server's static IP addresses
  </Step>

  <Step title="Test Access">
    Verify API access from whitelisted IPs
  </Step>
</Steps>

<Warning>
  IP whitelisting is only recommended for server-to-server communication with static IPs.
</Warning>

## Error Handling

### Authentication Errors

Common authentication error responses:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "status": 401
  }
}
```

### Error Codes

| Code           | Status | Description                            |
| -------------- | ------ | -------------------------------------- |
| `unauthorized` | 401    | Missing or invalid API key             |
| `forbidden`    | 403    | Valid key but insufficient permissions |
| `rate_limited` | 429    | Too many requests                      |
| `key_expired`  | 401    | API key has expired                    |

## Monitoring Usage

Track your API key usage in the dashboard:

### Available Metrics

* Request count by endpoint
* Error rates
* Response times
* Geographic distribution
* Top endpoints

### Usage Alerts

Set up alerts for:

* Approaching rate limits
* Unusual activity patterns
* Failed authentication attempts
* Key expiration reminders

## Support

<CardGroup cols={2}>
  <Card title="Security Issues" icon="shield" href="mailto:security@hirepanda.com">
    Report security concerns immediately
  </Card>

  <Card title="API Support" icon="headset" href="mailto:api@hirepanda.com">
    Get help with authentication
  </Card>
</CardGroup>