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:

User ID - Which user is making the request
Organization ID - Which organization they belong to
Permissions - What operations they can perform
Expiration - When the token expires

The token automatically scopes all API requests to that organization.

Token Claims

{
  "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

curl -X GET "https://api.artosai.com/api/v1/documents/" \
  -H "Authorization: Bearer TOKEN"

What Happens:

API validates Bearer token
Extracts organization ID from token (org_id: "org-A")
Queries only documents in org-A
Returns org-A documents only

User in Organization A sees:

{
  "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):

{
  "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:

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:

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:

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:

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

# 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

# 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:

# 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:

# 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

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

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

Authentication - Bearer token authentication
API Reference - Resource access patterns
Best Practices - Security best practices

​Organization Model

​What is an Organization?

​Multi-Tenancy Architecture

​Bearer Token Organization Context

​Token Claims

​Organization Scoping in API Calls

​Example: List Documents

​Resource Access Control

​1. Create Operations

​2. Read Operations

​3. Update Operations

​4. Delete Operations

​User Access Patterns

​Single Organization User

​Access Verification

​Data Isolation Guarantees

​Complete Isolation

​Storage Example

​Permission Levels

​User Role

​Admin Role

​Security Considerations

​1. Token Leakage

​2. User Removal

​3. Organization Deletion

​4. Cross-Organization Prevention

​Multi-Organization Users (Future)

​Organization Settings

​Audit and Compliance

​Best Practices

​1. Token Management

​2. User Management

​3. Data Management

​4. Security Monitoring

​Related Topics