# Access Policies

Access policies provide fine-grained control over what AI agents can do with files in your S3 buckets through Storage Connections. These policies work in conjunction with IAM permissions to define exactly which files and folders AI agents can read, write, create, or delete.

## Overview

When creating or managing a Storage Connection, you can define access policies that specify:

- **Actions**: What operations AI agents can perform (`FILE_READ`, `FILE_WRITE`, `FILE_CREATE`, `FILE_DELETE`)
- **Resources**: Which files and folders these actions apply to, using glob patterns

Access policies act as an additional security layer on top of IAM permissions, allowing you to control access at a more granular level without modifying your AWS IAM policies.

## When to Configure Access Policies

You can configure access policies:

1. **During Storage Connection Creation**: Set up access policies as part of the initial connection setup
2. **After Connection Creation**: Add, modify, or remove access policies from existing Storage Connections at any time

Access policies are recommended for all Storage Connections to ensure AI agents only access the specific files and folders they need.

## Policy Structure

Each access policy consists of one or more policy statements. Each statement contains:

### Actions

The operations allowed on matched files and folders:

| Action | Description | Required IAM Permission |
| --- | --- | --- |
| `FILE_READ` | Read and list files and folders | `s3:GetObject`, `s3:ListBucket` |
| `FILE_WRITE` | Overwrite existing files (does not allow creating new files) | `s3:PutObject` |
| `FILE_CREATE` | Create new files (does not allow overwriting existing files) | `s3:PutObject` |
| `FILE_DELETE` | Delete files and folders | `s3:DeleteObject` |

### Resources

Resources specify which files and folders the actions apply to using glob patterns. Each resource includes:

- **Bucket name**: The S3 bucket (automatically set from your Storage Connection)
- **Path patterns**: One or more glob patterns that match file and folder paths

## Supported Glob Patterns

Storage Connections support the following glob patterns for resource matching:

| Pattern | Matches | Example |
| --- | --- | --- |
| `**` | All files and directories recursively | Matches everything in the bucket |
| `example.txt` | An explicit file name at the root level | `example.txt` only |
| `foo/*` | Direct children of the `foo` directory | `foo/bar.txt`, `foo/data.json` (not `foo/sub/file.txt`) |
| `foo/**` | All files recursively under `foo` directory | `foo/bar.txt`, `foo/sub/file.txt`, `foo/a/b/c.txt` |
| `**/*.txt` | All `.txt` files recursively in any directory | Any `.txt` file anywhere in the bucket |
| `*.txt` | All `.txt` files at the root level only | Root-level `.txt` files (not in subdirectories) |
| `reports/**/*.pdf` | All PDF files under the `reports` directory | `reports/q1/summary.pdf`, `reports/2024/annual.pdf` |
| `data/*/output.json` | `output.json` files in direct subdirectories of `data` | `data/prod/output.json`, `data/test/output.json` |

## Configuring Access Policies

### During Storage Connection Creation

1. Navigate to **Storage Connections** in your Vendia dashboard

2. Click **\+ Connection** to create a new Storage Connection

3. Fill in the required connection details (Name, Role ARN, S3 Bucket Name, Bucket Region)

4. Under “Give AI agents full access to all files and folders in this S3 bucket?”:
   - Select **Yes** to grant full access (all actions) to the entire bucket (`**` pattern)
   - Select **No, I’d like to decide exactly which files/folders are accessible after creating this Storage Connection** to configure custom policies
5. Complete the Storage Connection creation

6. If you selected **No**, proceed to configure specific access policies in the next step

### After Storage Connection Creation

To add or modify access policies on an existing Storage Connection:

1. Navigate to **Storage Connections** in your Vendia dashboard

2. Select the Storage Connection you want to configure

3. Click the **Access Policy** tab

4. Click **\+ Add Path** to create a new policy statement

5. For each policy statement, specify:
   - **Path pattern**: The glob pattern matching files and folders
   - **Actions**: Select the allowed operations for this path pattern
6. Review your policies for conflicts or redundancies (the UI will notify you of issues)

7. Click **Save** to apply the changes

## Example Access Policy Configurations

### Read-Only Access to Documentation Folder

**Use Case**: AI agents need to read reference documentation but shouldn’t modify anything.

```
Pattern: docs/**

Actions: FILE_READ
```

### Create Reports but Don’t Overwrite

**Use Case**: AI agents generate reports but should never overwrite existing ones.

```
Pattern: reports/**/*.pdf

Actions: FILE_CREATE, FILE_READ
```

### Full Access to Temporary Workspace

**Use Case**: AI agents have complete control over a temporary working directory.

```
Pattern: workspace/temp/**

Actions: FILE_READ, FILE_WRITE, FILE_CREATE, FILE_DELETE
```

### Segregated Access by File Type

**Use Case**: AI agents can read all files, create new reports (without overwriting), and create/update analysis files.

```
Policy 1:

Pattern: **

Actions: FILE_READ

Policy 2:

Pattern: output/reports/**

Actions: FILE_CREATE

Policy 3:

Pattern: output/analysis/**/*.json

Actions: FILE_CREATE, FILE_WRITE
```

### Complex Multi-Tier Access

**Use Case**: Different access levels for different parts of the bucket.

```
Policy 1:

Pattern: reference/**

Actions: FILE_READ

Policy 2:

Pattern: drafts/**

Actions: FILE_READ, FILE_WRITE, FILE_CREATE

Policy 3:

Pattern: published/**

Actions: FILE_READ

Policy 4:

Pattern: workspace/**

Actions: FILE_READ, FILE_WRITE, FILE_CREATE, FILE_DELETE
```

## Complete Configuration Examples

These examples show how IAM policies and access policies work together to control what AI agents can actually do.

### Example 1: Read-Only Access to Documentation

**Scenario**: AI agents need to read reference documentation but shouldn’t modify anything.

**IAM Policy** (AWS level - sets outer boundary):

```
{

"Effect": "Allow",

"Action": ["s3:GetObject", "s3:ListBucket"],

"Resource": ["arn:aws:s3:::my-bucket", "arn:aws:s3:::my-bucket/*"]

}
```

**Access Policy** (Vendia level - further restricts):

```
Pattern: docs/**

Actions: FILE_READ
```

**Result**: AI agents can read files only in the `docs/` folder. Cannot write or delete anywhere (IAM doesn’t grant write/delete, and access policy limits to docs folder).

### Example 2: Controlled Report Generation

**Scenario**: AI agents can read source data and create new reports, but cannot overwrite existing reports.

**IAM Policy**:

```
{

"Effect": "Allow",

"Action": ["s3:GetObject", "s3:ListBucket", "s3:PutObject"],

"Resource": ["arn:aws:s3:::my-bucket", "arn:aws:s3:::my-bucket/*"]

}
```

**Access Policies**:

```
Policy 1:

Pattern: source-data/**

Actions: FILE_READ

Policy 2:

Pattern: reports/**/*.pdf

Actions: FILE_CREATE, FILE_READ
```

**Result**: AI agents can:

- Read from `source-data/`
- Create new PDF reports in `reports/` (but cannot overwrite existing ones due to FILE_CREATE)
- Read existing reports
- Cannot delete anything (no IAM permission)

### Example 3: Temporary Workspace with Full Control

**Scenario**: AI agents have complete control over a temporary workspace, but no access elsewhere.

**IAM Policy**:

```
{

"Effect": "Allow",

"Action": [

"s3:GetObject",

"s3:ListBucket",

"s3:PutObject",

"s3:DeleteObject"

],

"Resource": [

"arn:aws:s3:::my-bucket",

"arn:aws:s3:::my-bucket/workspace/temp/*"

]

}
```

**Access Policy**:

```
Pattern: workspace/temp/**

Actions: FILE_READ, FILE_WRITE, FILE_CREATE, FILE_DELETE
```

**Result**: AI agents have complete control (read, write, create, delete) but only in `workspace/temp/`. The IAM policy prevents access outside this folder, and the access policy grants all operations within it.

## How MCP Tools Use Access Policies

Each MCP tool respects the access policies configured for the Storage Connection:

### `list-storage-connection-contents`

- **Required Action**: `FILE_READ`
- Lists only files and folders that match patterns with read permissions
- Folders without any accessible files won’t be displayed

### `read-storage-connection-file`

- **Required Action**: `FILE_READ`
- Can only read files that match patterns with read permissions
- Returns authorization error if the file doesn’t match any read-enabled pattern

### `write-storage-connection-file`

- **Required Actions**:

- For new files: `FILE_CREATE`
  - For existing files: `FILE_WRITE`
- Checks if the file already exists:
  - If it exists and only `FILE_CREATE` is granted: Returns authorization error
  - If it exists and `FILE_WRITE` is granted: Overwrites the file
  - If it’s new and `FILE_CREATE` is granted: Creates the file

### `delete-storage-connection-file`

- **Required Action**: `FILE_DELETE`
- Can only delete files that match patterns with delete permissions
- Returns authorization error if the file doesn’t match any delete-enabled pattern

## Default Policy Behavior

### New Storage Connections

- If you choose **No** when asked about full access during creation, no default policy is applied
- You must explicitly configure access policies before AI agents can access any files

### Existing Storage Connections (Created Before Access Policies)

- Storage Connections created before access policies were introduced automatically have a default policy granting all actions for the entire bucket (`**` pattern)
- This preserves backward compatibility and existing behavior
- You can modify these policies at any time to restrict access

## Troubleshooting

### ”Access Denied” Errors

If AI agents receive access denied errors:

1. **Check IAM permissions**: Verify the IAM role has the required S3 permissions
2. **Review access policies**: Ensure the file path matches an access policy with the required action
3. **Verify glob patterns**: Test your glob patterns match the intended files
4. **Check for conflicts**: Look for more restrictive policies that override permissive ones

### Files Not Appearing in Lists

If expected files don’t appear when listing:

1. **Verify read permissions**: Ensure `FILE_READ` is granted for the path
2. **Check pattern matching**: Confirm your glob patterns cover the file locations
3. **Review IAM ListBucket permission**: Verify `s3:ListBucket` is granted in IAM

### Cannot Overwrite Existing Files

If AI agents can’t update existing files:

1. **Check for `FILE_CREATE` only**: Verify the policy includes `FILE_WRITE`, not just `FILE_CREATE`
2. **Confirm IAM permissions**: Ensure `s3:PutObject` is granted in the IAM role
3. **Review path patterns**: Ensure the file path matches a write-enabled pattern

### Cannot Delete Files

If AI agents can’t delete files:

1. **Verify `FILE_DELETE` permission**: Ensure `FILE_DELETE` is granted for the path
2. **Check IAM permissions**: Confirm `s3:DeleteObject` is in the IAM role
3. **Review path matching**: Ensure the file path matches a delete-enabled pattern