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

# Authentication

> Learn how to authenticate with the taap.it API using API keys

The taap.it API uses API key-based authentication to secure access to your account and resources. All API requests must include a valid API key in the Authorization header.

## API Key Overview

API keys provide secure access to your taap.it account and are created through the web application dashboard. Each API key is:

* **User-specific**: Tied to your user account
* **Scoped**: Can have full access, read-only access, or limited permissions
* **Secure**: Prefixed with `taapit_` and cryptographically generated

## Creating API Keys

<Steps>
  <Step title="Access API Settings">
    Log into your taap.it dashboard and navigate to your user settings.
  </Step>

  <Step title="Generate New Key">
    In the "API Keys" section, click "Create API Key" and provide a descriptive name.
  </Step>

  <Step title="Set Permissions">
    Choose the appropriate permission level for your use case:

    * **Full Access**: Complete read/write access to all resources
    * **Read Only**: View-only access to all resources
    * **Limited Access**: Custom permissions for specific resources
  </Step>

  <Step title="Store Securely">
    Copy the generated API key immediately and store it securely.

    <Warning>
      API keys are only displayed once during creation. If lost, you'll need to generate a new key.
    </Warning>
  </Step>
</Steps>

## Using API Keys

Include your API key in the Authorization header using the Bearer token format:

```http theme={null}
Authorization: Bearer taapit_your_api_key_here
```

### Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.taap.it/v1/workspaces' \
    -H 'Authorization: Bearer taapit_abc123def456ghi789' \
    -H 'Content-Type: application/json'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.taap.it/v1/workspaces', {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  });
  ```

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

  headers = {
      'Authorization': f'Bearer {api_key}',
      'Content-Type': 'application/json'
  }

  response = requests.get('https://api.taap.it/v1/workspaces', headers=headers)
  ```

  ```php PHP theme={null}
  <?php
  $headers = [
      'Authorization: Bearer ' . $api_key,
      'Content-Type: application/json'
  ];

  $response = file_get_contents('https://api.taap.it/v1/workspaces', false, 
      stream_context_create(['http' => ['header' => implode("\r\n", $headers)]])
  );
  ?>
  ```
</CodeGroup>

## Permission Levels

API keys can have different permission levels that control access to resources:

### Full Access

<Check>
  Grants complete read and write access to all resources and endpoints.
</Check>

* **Use case**: Server-to-server integrations, administrative tools
* **Permissions**: All read and write operations
* **Security**: High - monitor usage carefully

### Read Only

<Info>
  Provides view-only access to all resources without modification capabilities.
</Info>

* **Use case**: Analytics dashboards, reporting tools
* **Permissions**: GET operations only
* **Security**: Medium - data exposure limited to viewing

### Limited Access

<Tip>
  Custom permissions allow granular control over specific resources and operations.
</Tip>

* **Use case**: Third-party integrations with specific needs
* **Permissions**: Configurable per resource (domains, links, projects, workspaces, analytics)
* **Security**: High - minimal necessary permissions

## Security Best Practices

<AccordionGroup>
  <Accordion title="Key Storage">
    * Store API keys in environment variables, not in code
    * Use secure key management services for production
    * Never commit API keys to version control
    * Rotate keys regularly for enhanced security
  </Accordion>

  <Accordion title="Access Control">
    * Use the principle of least privilege
    * Create separate keys for different environments
    * Monitor API key usage and set up alerts
    * Deactivate unused or compromised keys immediately
  </Accordion>

  <Accordion title="Network Security">
    * Always use HTTPS for API requests
    * Implement proper error handling
    * Use IP whitelisting when possible
    * Monitor for suspicious activity
  </Accordion>
</AccordionGroup>

## Error Handling

### Authentication Errors

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "detail": "Invalid API key"
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "detail": "Insufficient permissions for this operation"
  }
  ```
</ResponseExample>

### Common Authentication Issues

<AccordionGroup>
  <Accordion title="Invalid API Key">
    * Verify the key is copied correctly
    * Check that the key hasn't been deactivated
    * Ensure you're using the full key including the `taapit_` prefix
  </Accordion>

  <Accordion title="Permission Denied">
    * Check if your API key has the required permissions
    * Verify you're trying to access resources you own
    * Consider upgrading to a key with full access
  </Accordion>

  <Accordion title="Rate Limiting">
    * Monitor your request frequency
    * Implement exponential backoff
    * Check the rate limit headers in responses
  </Accordion>
</AccordionGroup>

## Migration Guide

If you're migrating from another authentication method or upgrading your integration:

<Steps>
  <Step title="Create New API Key">
    Generate a new API key with appropriate permissions for your use case.
  </Step>

  <Step title="Test Integration">
    Update your application to use the new API key and test thoroughly.
  </Step>

  <Step title="Deactivate Old Key">
    Once confirmed working, deactivate any old authentication credentials.
  </Step>
</Steps>

<Card title="Ready to authenticate?" icon="key" href="/quickstart">
  Follow our quickstart guide to make your first authenticated API call.
</Card>