# Tigris Security & Access Control

Configure access keys, CORS rules, bucket visibility, and presigned URL security for Tigris object storage. Covers key lifecycle management, role-based access, and security auditing.

## When to use[​](#when-to-use "Direct link to When to use")

Use when configuring CORS, rotating access keys, setting bucket policies, or securing Tigris storage — covers key lifecycle, roles, CORS rules, presigned URL security, audit checklist

## Install the skill[​](#install-the-skill "Direct link to Install the skill")

```
npx skills add tigrisdata/skills --skill tigris-security-access-control
```

This page is generated from [`skills/tigris-security-access-control/SKILL.md`](https://github.com/tigrisdata/skills/blob/main/skills/tigris-security-access-control/SKILL.md) in the [tigrisdata/skills](https://github.com/tigrisdata/skills) repository.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

**Before doing anything else**, install the Tigris CLI if it's not already available:

```
tigris help || npm install -g @tigrisdata/cli
```

If you need to install it, tell the user: "I'm installing the Tigris CLI (`@tigrisdata/cli`) so we can work with Tigris object storage."

## Quick Reference[​](#quick-reference "Direct link to Quick Reference")

| Operation        | Command                                                         |
| ---------------- | --------------------------------------------------------------- |
| Create key       | `tigris access-keys create "my-key"`                            |
| List keys        | `tigris access-keys list`                                       |
| Assign to bucket | `tigris access-keys assign <tid> --bucket <name> --role Editor` |
| Revoke key       | `tigris access-keys delete <tid>`                               |
| Set CORS         | `tigris buckets cors set <bucket> --config cors.json`           |
| Get CORS         | `tigris buckets cors get <bucket>`                              |
| Remove CORS      | `tigris buckets cors delete <bucket>`                           |

***

## Access Key Lifecycle[​](#access-key-lifecycle "Direct link to Access Key Lifecycle")

### Create[​](#create "Direct link to Create")

```
tigris access-keys create "production-app-key"

# Output:

# Access Key ID: tid_xxx

# Secret Access Key: tsec_yyy  ← shown ONLY once, save immediately
```

### Assign to Bucket[​](#assign-to-bucket "Direct link to Assign to Bucket")

```
# Editor: read + write + delete

tigris access-keys assign tid_xxx --bucket my-app-uploads --role Editor



# ReadOnly: read only

tigris access-keys assign tid_xxx --bucket my-app-uploads --role ReadOnly
```

| Role       | Read | Write | Delete | Use When                             |
| ---------- | ---- | ----- | ------ | ------------------------------------ |
| `Editor`   | Yes  | Yes   | Yes    | App servers that upload/modify files |
| `ReadOnly` | Yes  | No    | No     | Services that only read/serve files  |

### Scope Keys Narrowly[​](#scope-keys-narrowly "Direct link to Scope Keys Narrowly")

Create separate keys for different concerns:

```
# Key for the app server (read/write to uploads bucket)

tigris access-keys create "app-server"

tigris access-keys assign tid_app --bucket app-uploads --role Editor



# Key for the CDN/read service (read-only)

tigris access-keys create "cdn-reader"

tigris access-keys assign tid_cdn --bucket app-uploads --role ReadOnly



# Key for backups (write to backup bucket only)

tigris access-keys create "backup-writer"

tigris access-keys assign tid_bak --bucket app-backups --role Editor
```

### Rotate Keys (Zero Downtime)[​](#rotate-keys-zero-downtime "Direct link to Rotate Keys (Zero Downtime)")

```
# 1. Create new key

tigris access-keys create "production-app-key-v2"

tigris access-keys assign tid_new --bucket my-app-uploads --role Editor



# 2. Update application environment with new key

# (deploy with new TIGRIS_STORAGE_ACCESS_KEY_ID / SECRET)



# 3. Verify app works with new key



# 4. Revoke old key

tigris access-keys delete tid_old
```

### List and Audit[​](#list-and-audit "Direct link to List and Audit")

```
# List all access keys

tigris access-keys list



# Check which buckets a key can access

tigris access-keys info tid_xxx
```

***

## CORS Configuration[​](#cors-configuration "Direct link to CORS Configuration")

CORS is required for browser-based uploads (direct uploads, presigned PUT URLs).

### Set CORS Rules[​](#set-cors-rules "Direct link to Set CORS Rules")

```
tigris buckets cors set my-app-uploads --config cors.json
```

### Development (Localhost)[​](#development-localhost "Direct link to Development (Localhost)")

```
{

  "CORSRules": [

    {

      "AllowedOrigins": ["http://localhost:3000", "http://localhost:5173"],

      "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],

      "AllowedHeaders": ["*"],

      "ExposeHeaders": ["ETag", "Content-Length"],

      "MaxAgeSeconds": 3600

    }

  ]

}
```

### Production (Specific Domain)[​](#production-specific-domain "Direct link to Production (Specific Domain)")

```
{

  "CORSRules": [

    {

      "AllowedOrigins": ["https://myapp.com", "https://www.myapp.com"],

      "AllowedMethods": ["GET", "PUT", "HEAD"],

      "AllowedHeaders": ["Content-Type", "Content-MD5", "Content-Disposition"],

      "ExposeHeaders": ["ETag"],

      "MaxAgeSeconds": 86400

    }

  ]

}
```

### Combined Dev + Production[​](#combined-dev--production "Direct link to Combined Dev + Production")

```
{

  "CORSRules": [

    {

      "AllowedOrigins": [

        "https://myapp.com",

        "https://www.myapp.com",

        "http://localhost:3000"

      ],

      "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],

      "AllowedHeaders": ["*"],

      "ExposeHeaders": ["ETag", "Content-Length"],

      "MaxAgeSeconds": 3600

    }

  ]

}
```

### Permissive (Any Origin)[​](#permissive-any-origin "Direct link to Permissive (Any Origin)")

```
{

  "CORSRules": [

    {

      "AllowedOrigins": ["*"],

      "AllowedMethods": ["GET"],

      "AllowedHeaders": ["*"],

      "MaxAgeSeconds": 86400

    }

  ]

}
```

**Warning:** Only use `"*"` origins for truly public, read-only content. Never allow `PUT`/`DELETE` from any origin.

### Verify CORS[​](#verify-cors "Direct link to Verify CORS")

```
# Check current CORS config

tigris buckets cors get my-app-uploads



# Test with curl

curl -I -H "Origin: https://myapp.com" \

  -H "Access-Control-Request-Method: PUT" \

  -X OPTIONS \

  https://my-app-uploads.t3.storage.dev/test
```

***

## Public vs Private Buckets[​](#public-vs-private-buckets "Direct link to Public vs Private Buckets")

| Setting           | Who Can Read                | URL Access     | Use For                                   |
| ----------------- | --------------------------- | -------------- | ----------------------------------------- |
| Private (default) | Only authenticated requests | Presigned URLs | User documents, sensitive files           |
| Public            | Anyone with URL             | Direct URL     | Static assets, public images, CDN content |

```
# Create public bucket

tigris buckets create my-public-assets --public



# Create private bucket (default)

tigris buckets create my-private-docs
```

***

## Presigned URL Security[​](#presigned-url-security "Direct link to Presigned URL Security")

### Best Practices[​](#best-practices "Direct link to Best Practices")

| Parameter             | Recommendation                          |
| --------------------- | --------------------------------------- |
| Expiration (download) | 5-60 minutes for most use cases         |
| Expiration (upload)   | 5-15 minutes                            |
| Scope                 | One URL per file, one operation per URL |

```
import { getPresignedUrl } from "@tigrisdata/storage";



// Short-lived download URL

const { data } = await getPresignedUrl("documents/report.pdf", {

  operation: "get",

  expiresIn: 300, // 5 minutes

});



// Short-lived upload URL with content type restriction

const { data } = await getPresignedUrl("uploads/photo.jpg", {

  operation: "put",

  expiresIn: 600,

  contentType: "image/jpeg", // Client must upload this type

});
```

### Never Do[​](#never-do "Direct link to Never Do")

* Set expiration longer than 24 hours
* Generate presigned URLs for entire bucket prefixes
* Share presigned URLs in public channels (they're secrets)
* Use presigned URLs as permanent links (use public bucket URLs instead)

***

## Environment Variable Security[​](#environment-variable-security "Direct link to Environment Variable Security")

```
# .env (never commit this file)

TIGRIS_STORAGE_ACCESS_KEY_ID=tid_xxx

TIGRIS_STORAGE_SECRET_ACCESS_KEY=tsec_yyy
```

```
# .gitignore (must include)

.env

.env.local

.env.*.local
```

For CI/CD, use your platform's secrets management:

```
# GitHub Actions

gh secret set TIGRIS_STORAGE_ACCESS_KEY_ID

gh secret set TIGRIS_STORAGE_SECRET_ACCESS_KEY



# Vercel

vercel env add TIGRIS_STORAGE_ACCESS_KEY_ID



# Fly.io

fly secrets set TIGRIS_STORAGE_ACCESS_KEY_ID=tid_xxx
```

***

## Security Audit Checklist[​](#security-audit-checklist "Direct link to Security Audit Checklist")

* [ ] **No keys in code** — search for `tid_` and `tsec_` in your repo
* [ ] **`.env` in `.gitignore`** — credentials never committed
* [ ] **Keys scoped to buckets** — no unassigned keys with global access
* [ ] **Roles match need** — read-only services use `ReadOnly` role
* [ ] **CORS not overly permissive** — no `"*"` origin with write methods
* [ ] **Presigned URLs have short expiry** — under 1 hour for most cases
* [ ] **Unused keys revoked** — no stale keys from former team members or old deployments
* [ ] **Separate keys per environment** — dev/staging/production use different keys

***

## Key Compromise Response[​](#key-compromise-response "Direct link to Key Compromise Response")

If an access key is exposed (committed to git, leaked in logs, etc.):

```
# 1. Immediately revoke the compromised key

tigris access-keys delete tid_compromised



# 2. Create a new key

tigris access-keys create "replacement-key"

tigris access-keys assign tid_new --bucket my-bucket --role Editor



# 3. Update all deployments with the new key

# (update .env, CI/CD secrets, deployment configs)



# 4. Audit access — check for unauthorized uploads/downloads

tigris ls t3://my-bucket --recursive -l | sort -k4 -r | head -50



# 5. If key was committed to git, rotate and consider the entire

#    git history compromised — use git-filter-repo to remove it
```

***

## Critical Rules[​](#critical-rules "Direct link to Critical Rules")

**Always:** Create separate keys per environment and concern | Assign keys to specific buckets with minimum required role | Rotate keys periodically (quarterly recommended) | Set CORS to specific origins in production | Use short-lived presigned URLs

**Never:** Commit keys to git | Use a single key for all environments | Set CORS to `"*"` with write methods | Share presigned URLs publicly | Keep unused keys active

***

## Known Issues[​](#known-issues "Direct link to Known Issues")

| Problem                            | Fix                                                               |
| ---------------------------------- | ----------------------------------------------------------------- |
| CORS preflight fails               | Check `AllowedOrigins` includes your exact origin (with protocol) |
| "Access denied" after key rotation | Ensure new key is assigned to bucket with correct role            |
| Secret key lost                    | Cannot recover — create new key and reassign                      |
| Browser upload fails silently      | Check CORS config includes `PUT` in `AllowedMethods`              |

***

## Related Skills[​](#related-skills "Direct link to Related Skills")

* **file-storage** — CLI setup and access key creation
* **tigris-s3-migration** — CORS and credential setup during migration

## Official Documentation[​](#official-documentation "Direct link to Official Documentation")

* Tigris: <https://www.tigrisdata.com/docs/>
