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

# Organization Model

> Understanding Artos multi-tenancy and organization scoping

# Organization Model

Artos uses a multi-tenant architecture where each organization's data is completely isolated. This guide explains how organization scoping works and how it protects your data.

## What is an Organization?

An organization is a complete isolated environment that contains:

* **Users** - People with access to the organization
* **Resources** - Templates, documents, files, etc.
* **Settings** - Configuration and preferences
* **Data** - All documents and content created by the organization

Each organization's data is completely separate from all other organizations.

## Multi-Tenancy Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                      Artos Platform                              │
├──────────────────┬──────────────────┬──────────────────────────┤
│   Organization A │   Organization B │    Organization C        │
├──────────────────┼──────────────────┼──────────────────────────┤
│ Users:           │ Users:           │ Users:                   │
│ ├─ alice@a.com   │ ├─ bob@b.com     │ ├─ charlie@c.com         │
│ └─ dave@a.com    │ └─ eve@b.com     │ └─ frank@c.com           │
│                  │                  │                          │
│ Resources:       │ Resources:       │ Resources:               │
│ ├─ templates     │ ├─ templates     │ ├─ templates             │
│ ├─ documents     │ ├─ documents     │ ├─ documents             │
│ ├─ files         │ ├─ files         │ ├─ files                 │
│ └─ sets          │ └─ sets          │ └─ sets                  │
│                  │                  │                          │
│ Storage:         │ Storage:         │ Storage:                 │
│ └─ isolated      │ └─ isolated      │ └─ isolated              │
└──────────────────┴──────────────────┴──────────────────────────┘
```

## Bearer Token Organization Context

When a user authenticates with a Bearer token, the token contains:

1. **User ID** - Which user is making the request
2. **Organization ID** - Which organization they belong to
3. **Permissions** - What operations they can perform
4. **Expiration** - When the token expires

The token automatically scopes all API requests to that organization.

### Token Claims

```json theme={null}
{
  "sub": "user-uuid",           // User ID
  "org_id": "org-uuid",         // Organization ID
  "email": "user@example.com",
  "role": "admin",              // Permission level
  "exp": 1706012400            // Expiration timestamp
}
```

## Organization Scoping in API Calls

Every API call using a Bearer token is automatically scoped to the authenticated user's organization.

### Example: List Documents

```bash theme={null}
curl -X GET "https://api.artosai.com/api/v1/documents/" \
  -H "Authorization: Bearer TOKEN"
```

**What Happens**:

1. API validates Bearer token
2. Extracts organization ID from token (`org_id: "org-A"`)
3. Queries only documents in `org-A`
4. Returns `org-A` documents only

**User in Organization A sees**:

```json theme={null}
{
  "documents": [
    {"document_id": "doc-1", "organization_id": "org-A"},
    {"document_id": "doc-2", "organization_id": "org-A"}
  ]
}
```

**User in Organization B sees** (using different token):

```json theme={null}
{
  "documents": [
    {"document_id": "doc-3", "organization_id": "org-B"}
  ]
}
```

Neither user can see the other's documents.

## Resource Access Control

### 1. Create Operations

When creating a resource, it's automatically associated with your organization:

```bash theme={null}
POST /api/v1/documents/generate
{
  "document_type": "CSR",
  ...
}
```

The created document automatically has:

* `organization_id: "your-org-id"` (from token)
* `created_by: "your-user-id"` (from token)
* Accessible only to users in your organization

### 2. Read Operations

All read operations automatically filter by organization:

```bash theme={null}
GET /api/v1/templates/template-id
→ Returns template ONLY if it belongs to your organization
→ Returns 404 if template belongs to different organization
```

### 3. Update Operations

Updates only work on resources in your organization:

```bash theme={null}
PUT /api/v1/templates/template-id
→ Succeeds if template is in your organization
→ Returns 403 if template belongs to different organization
```

### 4. Delete Operations

Deletion only works on resources in your organization:

```bash theme={null}
DELETE /api/v1/templates/template-id
→ Succeeds if template is in your organization
→ Returns 403 if template belongs to different organization
```

## User Access Patterns

### Single Organization User

```
User: alice@example.com
├─ Organization: Pharma Corp
├─ Bearer Token: contains org_id="pharma-corp"
└─ Can Access: All Pharma Corp resources
```

### Access Verification

When Alice makes an API call:

```
Token: Bearer {claims: {user_id: "alice", org_id: "pharma-corp"}}
        ↓
API Request to /documents/template-uuid
        ↓
Verify Token → Extract org_id="pharma-corp"
        ↓
Query Database WHERE template_id="template-uuid" AND org_id="pharma-corp"
        ↓
Return template (if it exists)
```

## Data Isolation Guarantees

### Complete Isolation

Organizations have complete data isolation:

* **Network Isolation** - Data queries are scoped by organization
* **Database Isolation** - Filters applied at query level
* **File Isolation** - S3 paths include organization ID
* **No Cross-Organization Access** - Impossible to accidentally access other org's data

### Storage Example

Files are stored with organization path:

```
S3 Bucket Structure:
├─ pharma-corp/
│  ├─ templates/
│  │  └─ csr-template.docx
│  ├─ documents/
│  │  └─ csr-final.docx
│  └─ files/
│      └─ protocol.pdf
└─ biotech-inc/
   ├─ templates/
   ├─ documents/
   └─ files/
```

Each organization has isolated storage within the same bucket.

## Permission Levels

Different permission levels control what users can do:

### User Role

* Can view and download documents
* Can generate new documents
* Cannot create templates
* Cannot modify other users' work
* Cannot access admin functions

```bash theme={null}
# User can do this
POST /api/v1/documents/generate
GET /api/v1/documents/

# User cannot do this
POST /api/v1/templates/
DELETE /api/v1/templates/template-id
GET /api/v1/organization/settings
```

### Admin Role

* All user permissions
* Can create and manage templates
* Can manage organization settings
* Can view audit logs
* Can manage other users
* Can configure integrations

```bash theme={null}
# Admin can do all of the above, plus:
POST /api/v1/templates/
PUT /api/v1/organization/settings
DELETE /api/v1/templates/
GET /api/v1/audit-logs/
```

## Security Considerations

### 1. Token Leakage

If a token is leaked:

* Only that organization's data is exposed
* Other organizations are protected
* Token can be revoked without affecting others
* Rotate token immediately if compromised

### 2. User Removal

When a user is removed from organization:

* Token immediately becomes invalid
* User can no longer access any resources
* Historical data remains (for audit)
* User has no way to re-access data

### 3. Organization Deletion

When organization is deleted:

* All organization data is deleted
* All user tokens become invalid
* Cannot be undone

### 4. Cross-Organization Prevention

The system prevents cross-organization access:

```python theme={null}
# Even if a user knows the ID of another org's resource:
GET /api/v1/documents/other-org-doc-id
→ 404 Not Found (not 403 Forbidden)
→ Treated as if resource doesn't exist
```

This prevents information leakage about what resources exist in other orgs.

## Multi-Organization Users (Future)

In the future, Artos may support users belonging to multiple organizations:

```
User: alice@consulting.com
├─ Membership 1: Pharma Corp (Admin)
├─ Membership 2: Biotech Inc (User)
└─ Membership 3: CRO Corp (Viewer)
```

Token selection would determine which org is active:

```bash theme={null}
# Token scoped to Pharma Corp
Authorization: Bearer token-pharma
GET /api/v1/documents/
→ Returns Pharma Corp documents

# Token scoped to Biotech Inc
Authorization: Bearer token-biotech
GET /api/v1/documents/
→ Returns Biotech Inc documents
```

Currently, users belong to a single organization.

## Organization Settings

Organizations can configure:

* **Name** - Display name
* **Timezone** - For timestamps and scheduling
* **Style Guide** - Default formatting rules
* **Storage** - File retention policy
* **Integrations** - Connected services
* **Users** - Team members and permissions

```bash theme={null}
GET /api/v1/organization/settings
→ Returns organization configuration
```

## Audit and Compliance

All operations within an organization are tracked:

* **Who** - User ID performing action
* **What** - Operation performed
* **When** - Timestamp
* **Resource** - What was accessed/modified
* **Organization** - Which org it belongs to

```bash theme={null}
GET /api/v1/audit-logs/
→ Returns organization's audit log
→ Only visible to admin users
```

This enables:

* Compliance auditing
* Security investigation
* Usage tracking
* Regulatory compliance

## Best Practices

### 1. Token Management

* **Rotate regularly** - Get new tokens periodically
* **Store securely** - Use environment variables, not hardcoded
* **Monitor usage** - Check audit logs for unusual activity
* **Revoke if leaked** - Request new token immediately

### 2. User Management

* **Principle of Least Privilege** - Give minimum necessary permissions
* **Remove unused accounts** - Delete inactive users
* **Review access regularly** - Audit who has access
* **Use roles** - Don't create custom permissions

### 3. Data Management

* **Regular backups** - Download important documents
* **Archive old docs** - Remove temporary documents
* **Version control** - Keep template versions
* **Document changes** - Track modifications

### 4. Security Monitoring

* **Review audit logs** - Check for suspicious activity
* **Monitor failed auth** - Watch for unauthorized access attempts
* **Set alerts** - Notify on unusual operations
* **Update tokens** - Rotate on schedule

## Related Topics

* **[Authentication](../api-reference/authentication)** - Bearer token authentication
* **[API Reference](../api-reference/introduction)** - Resource access patterns
* **[Best Practices](../guides/quickstart)** - Security best practices