TAXII 2.x Collections & API Roots

Understanding the TAXII 2.x resource hierarchy.

API Roots

API roots are top-level groupings for collections.

Properties

Use Cases

• By Department: “SOC”, “Threat Intel”, “Incident Response”
• By Access Level: “Public”, “Partners”, “Internal”
• By Data Type: “Malware”, “Phishing”, “Network IOCs”

Default API Root

The default API root is accessible at /taxii2/default/:

taxii-cli api-root add --title "Primary Intel" --default

Other API roots use their title (slugified):

• “Threat Intel” → /taxii2/threat-intel/

Collections

Collections store STIX 2.x objects.

Properties

Collection ID vs Title

The id (UUID) is the canonical identifier:

86c1741e-7e95-4b17-8940-a8f83eb5fe32

The title is for display only:

• Multiple collections can have the same title
• Titles can be changed without affecting integrations
• Never use title for permissions

Example:

API Root: "Threat Intel"
├── Collection "IOCs" (id: 86c1741e-...)
├── Collection "IOCs" (id: 24574d4d-...)  ← Same title, different collection!
└── Collection "Malware" (id: f1e2d3c4-...)

Using Alias

Alias provides a friendly URL alternative to UUID:

taxii-cli collection add \
  --api-root-id <uuid> \
  --title "IP Blocklist" \
  --alias blocklist

Access options:

• By UUID: /taxii2/default/collections/86c1741e-.../
• By alias: /taxii2/default/collections/blocklist/

Note

Alias must be unique within an API root but can duplicate across API roots.

Access Control

Public Collections

Public collections allow unauthenticated access:

# Read-only public
taxii-cli collection add \
  --api-root-id <uuid> \
  --title "Public Feed" \
  --public

# Fully public (not recommended)
taxii-cli collection add \
  --api-root-id <uuid> \
  --title "Open Submission" \
  --public \
  --public-write

Permission-Based Access

For non-public collections, configure permissions per user:

accounts:
  - username: analyst
    permissions:
      86c1741e-7e95-4b17-8940-a8f83eb5fe32: [read]        # Read only
      24574d4d-d29a-4b53-80c0-be454dfac6d5: [read, write] # Full access

Collection Endpoints

Each collection provides these endpoints:

Finding Collection UUIDs

Via CLI

taxii-cli collection list --api-root-id <api-root-uuid>

Via API

curl http://localhost:9000/taxii2/default/collections/ \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "collections": [
    {
      "id": "86c1741e-7e95-4b17-8940-a8f83eb5fe32",
      "title": "IOC Feed",
      "can_read": true,
      "can_write": true,
      "media_types": ["application/stix+json;version=2.1"]
    }
  ]
}

Collection Management

Update Collection (Not Supported)

Currently, collections cannot be updated after creation. Delete and recreate if changes are needed.

Delete Collection

taxii-cli collection delete --id 86c1741e-7e95-4b17-8940-a8f83eb5fe32

Caution

This deletes all objects in the collection.

Move Objects Between Collections

Not directly supported. Export objects and re-import to new collection.

Best Practices

1. Use meaningful titles - But remember they’re for humans, not code
2. Use aliases for stable URLs - If you share URLs with partners
3. Note UUIDs immediately - Copy them when you create collections
4. One purpose per collection - Don’t mix unrelated data
5. Consider API root structure - Group related collections logically

Next Steps

• API Reference - REST API examples
• Permissions - Access control details