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

# Authentication

> Learn how to authenticate with the InstaView API using API keys

## Overview

The InstaView API uses API keys for authentication. Each API key is associated with a company and has specific scopes that control what actions it can perform.

## API Key Format

InstaView API keys follow this format:

```
sk_1a2b3c4d5e6f7g8h9i0jklmnopqrstuv
```

* **Prefix**: `sk_` indicates a secret key
* **Key**: Random Base62-encoded string (URL-safe, no special characters)
* **Length**: Approximately 46 characters total

<Warning>
  **Never expose your API keys!** Keep them secure and never commit them to
  version control. Use environment variables or secret management systems.
</Warning>

## Authentication Method

### Bearer Token

Pass your API key in the `Authorization` header with the Bearer scheme:

```bash theme={null}
curl https://api.instaview.sk/jobs \
  -H "Authorization: Bearer sk_your_api_key_here"
```

This follows the industry-standard OAuth 2.0 Bearer token format for authentication.

## Creating API Keys

<Steps>
  <Step title="Log in to Dashboard">
    Access your [InstaView dashboard](https://app.instaview.sk)
  </Step>

  <Step title="Navigate to API Keys">Go to **Settings** → **API Keys**</Step>
  <Step title="Click Create Key">Click the **Create API Key** button</Step>

  <Step title="Configure the Key">
    * Give it a descriptive name (e.g., "Production Integration") - Select the
      required scopes - Optionally set an expiration date - Configure IP allowlist
      if needed
  </Step>

  <Step title="Save the Key">
    Copy the API key immediately - you won't see it again!
  </Step>
</Steps>

## Scopes and Permissions

API keys use scope-based access control. Each resource type has three permission levels:

<CardGroup cols={3}>
  <Card title="Read" icon="eye">
    View and list resources
  </Card>

  <Card title="Write" icon="pen">
    Create and update resources
  </Card>

  <Card title="Delete" icon="trash">
    Delete resources (soft delete)
  </Card>
</CardGroup>

### Available Scopes

| Resource   | Read Scope        | Write Scope        | Delete Scope        |
| ---------- | ----------------- | ------------------ | ------------------- |
| Jobs       | `read:jobs`       | `write:jobs`       | `delete:jobs`       |
| Candidates | `read:candidates` | `write:candidates` | `delete:candidates` |
| Interviews | `read:interviews` | `write:interviews` | -                   |
| Agents     | `read:agents`     | `write:agents`     | `delete:agents`     |
| Companies  | `read:companies`  | `write:companies`  | -                   |
| Billing    | `read:billing`    | -                  | -                   |

### Scope Examples

<Tabs>
  <Tab title="Read Only">
    ```json theme={null}
    {
      "scopes": [
        "read:jobs",
        "read:candidates",
        "read:interviews"
      ]
    }
    ```

    Perfect for analytics dashboards and reporting tools.
  </Tab>

  <Tab title="Full Access">
    ```json theme={null}
    {
      "scopes": [
        "read:jobs",
        "write:jobs",
        "delete:jobs",
        "read:candidates",
        "write:candidates",
        "delete:candidates",
        "read:interviews",
        "write:interviews",
        "read:agents",
        "write:agents",
        "delete:agents"
      ]
    }
    ```

    Complete access for primary integrations.
  </Tab>

  <Tab title="Candidate Management">
    ```json theme={null}
    {
      "scopes": [
        "read:candidates",
        "write:candidates",
        "read:jobs",
        "read:interviews"
      ]
    }
    ```

    Focused access for candidate management systems.
  </Tab>
</Tabs>

## Company Isolation

Every API key is scoped to a specific company. This ensures data isolation:

* Keys can only access resources within their company
* Cross-company access is prevented at the API level
* Each company's data is completely isolated

### Regular API Keys

Standard API keys are associated with a single company:

```bash theme={null}
# This key can only access resources for Company A
curl https://api.instaview.sk/jobs \
  -H "Authorization: Bearer sk_abc123def456ghi789jkl"
```

### ATS Integration Keys

ATS (Applicant Tracking System) keys have special privileges:

* Can create and manage multiple companies
* Must specify `companyId` query parameter for resource access
* Ideal for multi-tenant integrations

```bash theme={null}
# ATS key accessing Company B's resources
curl https://api.instaview.sk/jobs?companyId=company-b-uuid \
  -H "Authorization: Bearer sk_ats123xyz456abc789def"
```

<Info>
  ATS keys can only be created by InstaView administrators. Contact support if
  you need ATS integration capabilities.
</Info>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use Environment Variables" icon="code">
    Never hardcode API keys in your application code.

    ```bash theme={null}
    # .env file
    INSTAVIEW_API_KEY=sk_your_key_here
    ```

    ```javascript theme={null}
    // Node.js
    const apiKey = process.env.INSTAVIEW_API_KEY;
    ```
  </Accordion>

  {" "}

  <Accordion title="Rotate Keys Regularly" icon="rotate">
    * Rotate API keys every 90 days - Create a new key before revoking the old one
      to avoid downtime - Use the dashboard to manage key lifecycle
  </Accordion>

  {" "}

  <Accordion title="Use Minimal Scopes" icon="lock">
    Apply the principle of least privilege: - Only grant scopes that are
    absolutely necessary - Use read-only keys for analytics and reporting - Create
    separate keys for different integrations
  </Accordion>

  <Accordion title="Configure IP Allowlists" icon="network-wired">
    Restrict API key usage to specific IP addresses:

    ```json theme={null}
    {
      "allowedIPs": [
        "192.168.1.100",
        "10.0.0.0/8"
      ]
    }
    ```

    Keys will only work from these IP addresses.
  </Accordion>

  {" "}

  <Accordion title="Monitor Key Usage" icon="chart-line">
    * Review API key audit logs regularly - Set up alerts for unusual activity -
      Track key usage in the dashboard
  </Accordion>

  <Accordion title="Set Expiration Dates" icon="calendar">
    Configure automatic key expiration for temporary integrations:

    * Set expiration during key creation
    * Receive notifications before expiry
    * Ideal for contractor access or time-limited projects
  </Accordion>
</AccordionGroup>

## Key Management

### Listing Your Keys

View all API keys in your dashboard:

* Active keys and their scopes
* Last used timestamp
* Creation date
* Expiration date (if set)

### Suspending Keys

Temporarily disable a key without deleting it:

```javascript theme={null}
// Keys can be suspended via the dashboard
// or programmatically through the admin API
```

Suspended keys will return a `401 Unauthorized` error.

### Revoking Keys

Permanently revoke a compromised key:

<Warning>Revoked keys cannot be restored. Create a new key if needed.</Warning>

### Audit Logs

All API key operations are logged:

* Key creation and deletion
* Successful authentications
* Failed authentication attempts
* Scope changes
* Suspension and revocation events

## Common Authentication Errors

<ResponseField name="401 Unauthorized" type="error">
  Invalid or missing API key

  ```json theme={null}
  {
    "message": "Invalid API key",
    "error": "Unauthorized",
    "statusCode": 401
  }
  ```

  Note: The API returns a generic error message to prevent information leakage about which keys are valid.
</ResponseField>

<ResponseField name="403 Forbidden" type="error">
  Insufficient scopes for the requested operation

  ```json theme={null}
  {
    "message": "Insufficient permissions: Required scope write:jobs not found",
    "error": "Forbidden",
    "statusCode": 403
  }
  ```

  This error occurs when your API key doesn't have the required scope for the operation you're trying to perform.
</ResponseField>

<Info>
  **Rate Limiting**: Rate limiting is planned for future implementation.
  Currently, the API does not enforce rate limits, but this feature will be
  added soon. When implemented, you'll receive appropriate HTTP 429 responses
  with retry-after headers.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Keys Guide" icon="key" href="/guides/api-keys">
    Deep dive into API key management
  </Card>

  <Card title="Scopes & Permissions" icon="shield" href="/guides/scopes-and-permissions">
    Learn about scope-based access control
  </Card>

  <Card title="Rate Limiting" icon="gauge" href="/guides/rate-limiting">
    Understand rate limits and best practices
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/error-handling">
    Handle authentication errors properly
  </Card>
</CardGroup>