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

# Security & Compliance

> Data handling, authentication, access control, and compliance practices

Avala is built for teams that handle sensitive data — medical images, proprietary sensor recordings, and pre-release product imagery. This page covers how the platform protects your data at every layer, from network transport to access control.

## Data Protection

### Encryption

All data in the Avala platform is encrypted both in transit and at rest.

| Layer                       | Method        | Details                                                                                                                                      |
| --------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **In transit**              | TLS 1.2+      | All API and web traffic uses HTTPS. HTTP requests are redirected to HTTPS.                                                                   |
| **At rest (Avala-managed)** | AES-256       | Data stored in Avala's infrastructure is encrypted with AES-256 using AWS KMS managed keys.                                                  |
| **At rest (BYOS)**          | Your KMS keys | When using [cloud storage integration](/docs/integrations/cloud-storage), data stays encrypted with your own KMS keys. Avala never stores a copy. |
| **Database**                | AES-256       | PostgreSQL (Aurora) databases are encrypted at the volume level with AWS KMS.                                                                |
| **Backups**                 | AES-256       | Automated database backups inherit the same encryption as the primary database.                                                              |

### Data Residency

Avala's primary infrastructure runs in AWS **US West (Oregon)** region. For teams with data residency requirements:

* **Bring Your Own Storage (BYOS)**: Keep data in your preferred region and cloud provider. Avala reads data directly from your bucket — no cross-region copies.
* **API metadata**: Project configurations, task states, and annotation results are stored in Avala's US-based infrastructure.

<Info>
  If you need data residency for annotation metadata (not just source data), contact us at **[support@avala.ai](mailto:support@avala.ai)** to discuss dedicated deployment options.
</Info>

## Authentication

Avala supports multiple authentication methods depending on your use case.

### API Keys

API keys are the primary authentication method for programmatic access.

| Property          | Details                                                                                                         |
| ----------------- | --------------------------------------------------------------------------------------------------------------- |
| **Scope**         | Organization-level and governed by API key scopes; avoid leaving scopes empty for MCP and production automation |
| **Format**        | Alphanumeric string, transmitted via `X-Avala-Api-Key` header                                                   |
| **Creation**      | Mission Control > [Settings > Security](https://avala.ai/settings?section=security)                             |
| **Rotation**      | Create a new key, update your integrations, then delete the old key                                             |
| **Rate limiting** | Per-key rate limits apply (see [Rate Limits](/docs/api-reference/rate-limits))                                       |

For integrations with write capability (including MCP), create narrow-scope keys and disable write/delete MCP operations unless explicitly required.

```bash theme={null}
# Using an API key with cURL
curl https://api.avala.ai/api/v1/datasets/ \
  -H "X-Avala-Api-Key: your-api-key-here"
```

```python theme={null}
# Using an API key with the Python SDK
from avala import Client

client = Client(api_key="your-api-key-here")
# Or set the AVALA_API_KEY environment variable and omit the parameter
client = Client()
```

### JWT Authentication

The Mission Control web application uses JWT (JSON Web Token) authentication via Auth0.

| Property       | Details                                     |
| -------------- | ------------------------------------------- |
| **Provider**   | Auth0                                       |
| **Algorithm**  | RS256 (RSA with SHA-256)                    |
| **Token type** | Bearer token in `Authorization` header      |
| **Expiry**     | Tokens expire after a configurable duration |
| **Refresh**    | Automatic refresh via Auth0 session         |

### Session Authentication

Django session authentication is available for the admin interface and internal tools. Not recommended for external integrations.

## Access Control

### Organization Roles

Avala uses role-based access control (RBAC) at the organization level.

| Role       | View Data | Create/Edit | Manage Members | Billing & Settings | Delete Org |
| ---------- | --------- | ----------- | -------------- | ------------------ | ---------- |
| **Member** | Yes       | Yes         | No             | No                 | No         |
| **Admin**  | Yes       | Yes         | Yes            | No                 | No         |
| **Owner**  | Yes       | Yes         | Yes            | Yes                | Yes        |

### Team Permissions

Within an organization, teams provide finer-grained access control for projects and datasets.

| Permission         | Description                                                |
| ------------------ | ---------------------------------------------------------- |
| **Project access** | Control which teams can view or annotate specific projects |
| **Dataset access** | Restrict dataset visibility to specific teams              |
| **Review access**  | Designate which team members can perform quality reviews   |
| **Export access**  | Control who can create and download annotation exports     |

For detailed team configuration, see [Team Permissions](/docs/annotation/guides/team-permissions).

### Principle of Least Privilege

Follow these practices when configuring access:

1. **Use teams** to scope access to relevant projects and datasets
2. **Assign the minimum role** needed — use Member for annotators, Admin only for team managers
3. **Rotate API keys** when team members leave or roles change
4. **Use separate API keys** for different integrations (CI/CD, data pipeline, monitoring) so you can revoke independently

## API Security

### Rate Limiting

All API endpoints are rate-limited to prevent abuse and ensure fair usage.

| Tier                 | Requests per minute | Burst limit   |
| -------------------- | ------------------- | ------------- |
| **Standard**         | 100                 | 50 concurrent |
| **Upload endpoints** | 60                  | 10 concurrent |
| **Export endpoints** | 30                  | 5 concurrent  |

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1708700460
```

See [Rate Limits](/docs/api-reference/rate-limits) for detailed information and best practices.

### Input Validation

All API inputs are validated server-side:

* Request body schemas are enforced via Django REST Framework serializers
* File uploads are validated for type, size, and content
* SQL injection, XSS, and other OWASP Top 10 vulnerabilities are mitigated through Django's built-in protections and parameterized queries
* CSRF protection is enabled for session-based authentication

### Audit Logging

Key actions are logged for audit purposes:

| Event                         | Logged Data                               |
| ----------------------------- | ----------------------------------------- |
| API key creation/deletion     | User, timestamp, key identifier           |
| Member added/removed          | User, target member, role, timestamp      |
| Export created                | User, project, dataset, format, timestamp |
| Project configuration changed | User, project, changes, timestamp         |
| Data deletion                 | User, dataset/item, timestamp             |

## Cloud Storage Security (BYOS)

When using the Bring Your Own Storage model, security responsibilities are shared:

| Responsibility              | Avala                         | You                           |
| --------------------------- | ----------------------------- | ----------------------------- |
| Annotation metadata storage | Yes                           | No                            |
| Source data storage         | No                            | Yes                           |
| Source data encryption      | No                            | Yes (your KMS keys)           |
| Bucket access policy        | Provides required permissions | Configures IAM policy         |
| Network transport           | TLS for API calls             | TLS for S3/GCS access         |
| Data retention              | Annotation metadata only      | Full control over source data |
| Backup                      | Annotation metadata only      | Full control over source data |

### Minimum Permissions

When connecting a cloud storage bucket, grant only the permissions Avala needs:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket",
        "arn:aws:s3:::your-bucket/*"
      ]
    }
  ]
}
```

Add `s3:PutObject` only if you need Avala to write exports back to your bucket. Never grant `s3:DeleteObject` or full `s3:*` access.

## Network Security

| Control               | Implementation                                                        |
| --------------------- | --------------------------------------------------------------------- |
| **HTTPS enforcement** | All HTTP traffic redirects to HTTPS                                   |
| **HSTS**              | Strict-Transport-Security header enabled                              |
| **CDN**               | Static assets served via CloudFront with TLS termination              |
| **WAF**               | Web Application Firewall rules protect against common attack patterns |
| **DDoS protection**   | AWS Shield Standard enabled on all public endpoints                   |

## Incident Response

If you discover a security vulnerability or suspect unauthorized access:

1. **Report immediately** to **[security@avala.ai](mailto:security@avala.ai)**
2. Include the affected resources, timestamps, and any relevant logs
3. Avala's security team will acknowledge within 24 hours and provide a remediation timeline

## Compliance

| Standard  | Status                                          |
| --------- | ----------------------------------------------- |
| **SOC 2** | Certified                                       |
| **GDPR**  | Data processing agreements available on request |
| **HIPAA** | Available for enterprise plans with BAA         |

<Warning>
  For HIPAA-regulated data, contact **[support@avala.ai](mailto:support@avala.ai)** before uploading any protected health information (PHI) to ensure your account is configured with the appropriate safeguards.
</Warning>

## Security Checklist for New Teams

Use this checklist when onboarding your team to Avala:

| Step | Action                                                      |
| ---- | ----------------------------------------------------------- |
| 1    | Create an organization and set the owner                    |
| 2    | Invite members with the minimum required role               |
| 3    | Create teams to scope access to specific projects           |
| 4    | Generate API keys for each integration (not shared keys)    |
| 5    | Configure cloud storage with least-privilege IAM policies   |
| 6    | Enable multi-stage review for sensitive annotation projects |
| 7    | Document your key rotation schedule                         |
| 8    | Review audit logs monthly for unexpected access patterns    |

## Next Steps

<CardGroup cols={2}>
  <Card title="" icon="key" href="/docs/api-reference/authentication">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Authentication</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Set up API keys and start making authenticated requests.</p>
  </Card>

  <Card title="" icon="users" href="/docs/annotation/guides/team-permissions">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Team Permissions</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Configure teams and roles for your organization.</p>
  </Card>

  <Card title="" icon="cloud" href="/docs/integrations/cloud-storage">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Cloud Storage</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Connect your S3 or GCS bucket with least-privilege access.</p>
  </Card>

  <Card title="" icon="gauge" href="/docs/api-reference/rate-limits">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Rate Limits</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Understand API rate limits and optimize your usage.</p>
  </Card>
</CardGroup>