Configuring API Key Scopes

<h2>Understanding API Key Scopes</h2> <p>API key scopes allow you to control exactly what data and resources each API key can access. This is essential for security, especially when sharing keys with different applications, team members, or external integrations.</p> <p>UnifiedMemory.ai supports three types of scopes, each designed for different use cases. You can combine multiple scopes on a single API key to create precisely the access pattern you need.</p> <h2>The Three Scope Types</h2> <h3>Organization-Wide Access</h3> <p><strong>When to use:</strong> Full administrative access or broad integrations that need access to all projects.</p> <p>Organization-wide scopes grant access to all projects and topics within your organization. This is the most permissive scope type.</p> <p><strong>Use cases:</strong></p> <ul> <li>Administrative tools and dashboards</li> <li>Organization-level backup and sync operations</li> <li>Cross-project analytics and reporting</li> <li>Internal tools used by administrators</li> </ul> <p><strong>Security note:</strong> Use organization-wide scopes sparingly. Most applications don't need this level of access.</p> <h3>Project-Specific Access</h3> <p><strong>When to use:</strong> Applications or services that work with a specific project.</p> <p>Project scopes limit access to memories and topics within a single project. This is the most common scope type and provides a good balance between functionality and security.</p> <p><strong>Use cases:</strong></p> <ul> <li>Development tools working on a specific codebase</li> <li>CI/CD pipelines for a particular application</li> <li>Project-specific integrations (e.g., a Slack bot for one team)</li> <li>Third-party tools that only need access to one project</li> </ul> <p><strong>Example:</strong> An API key for your "Mobile App" project would only access memories related to mobile development, not your "Marketing Website" project.</p> <h3>Topic Pattern Access</h3> <p><strong>When to use:</strong> Fine-grained access to specific topics across projects using wildcard patterns.</p> <p>Topic pattern scopes use wildcards to match specific topic paths. This provides the most granular control and is useful for complex access requirements.</p> <p><strong>Pattern syntax:</strong></p> <ul> <li><code>*</code> - Matches any single path segment</li> <li><code>**</code> - Matches any number of path segments (including zero)</li> </ul> <p><strong>Pattern examples:</strong></p> <pre><code>frontend/* - Matches frontend/components, frontend/styles frontend/** - Matches all topics under frontend */api - Matches myapp/api, webapp/api **/deployment/** - Matches any deployment-related topic at any level</code></pre> <p><strong>Use cases:</strong></p> <ul> <li>Specialized tools that only work with certain topic types (e.g., only deployment configs)</li> <li>Read-only access to documentation topics across all projects</li> <li>Temporary access for contractors to specific feature areas</li> </ul> <h2>Filtering with Allow and Deny Lists</h2> <p>Each scope can include allow and deny filters for both topics and tags. These filters work together to create precise access rules.</p> <h3>Allow Topics/Tags</h3> <p>Specify exactly which topics or tags are accessible. If you specify allow filters, <strong>only</strong> those items are accessible.</p> <p><strong>Example:</strong> For a project scope, allow only topics: <code>api/authentication</code>, <code>api/database</code></p> <h3>Deny Topics/Tags</h3> <p>Exclude specific topics or tags from access. Deny rules take precedence over allow rules.</p> <p><strong>Example:</strong> Grant project access but deny topic: <code>secrets/production</code> to prevent access to production credentials.</p> <h3>Filter Combinations</h3> <p>You can use tags and topics together for powerful access control:</p> <ul> <li><strong>Allow tags:</strong> <code>public</code>, <code>documentation</code></li> <li><strong>Deny tags:</strong> <code>internal</code>, <code>confidential</code></li> <li><strong>Allow topics:</strong> <code>api/**</code></li> <li><strong>Deny topics:</strong> <code>api/admin/**</code></li> </ul> <p>This configuration would allow access to all API documentation topics marked as public, but exclude internal or admin-related content.</p> <h2>How Multiple Scopes Work Together</h2> <p>When you add multiple scopes to a single API key, the key gets access to the <strong>union</strong> of all scope permissions. This allows you to build complex access patterns by combining simple scopes.</p> <h3>Example: Development Team Key</h3> <pre><code>Scope 1: Project = "Frontend App" - Allow tags: development, staging

Scope 2: Project = "Backend API"

• Allow topics: api/public/**
• Deny tags: production

Result: Access to development/staging frontend resources AND public API topics (except production)</code></pre>

<h3>Example: Cross-Project Documentation Access</h3> <pre><code>Scope 1: Topic Pattern = "**/documentation/**" - Allow tags: public

Scope 2: Topic Pattern = "**/readme"

Result: Access to all documentation topics tagged "public" AND all readme topics across all projects</code></pre>

<h3>Best Practices for Multiple Scopes</h3> <ul> <li><strong>Start minimal:</strong> Begin with the most restrictive scope and add more only when needed</li> <li><strong>Use descriptive names:</strong> Name your API keys clearly to indicate what scopes they have</li> <li><strong>Document your strategy:</strong> Keep notes on why each scope was added</li> <li><strong>Review regularly:</strong> Audit API key scopes quarterly and remove unnecessary permissions</li> </ul> <h2>Step-by-Step: Creating a Scoped API Key</h2> <h3>Step 1: Navigate to API Keys</h3> <p>From your dashboard, go to <strong>Account → API Keys</strong>.</p> <h3>Step 2: Click "Generate New Key"</h3> <p>Enter a descriptive name and optional description for your key.</p> <h3>Step 3: Set Expiration</h3> <p>Choose an expiration period (maximum 90 days). Shorter periods are more secure.</p> <h3>Step 4: Add Scopes</h3> <p>Click <strong>"+ Add Scope"</strong> and select a scope type:</p> <p><strong>For Organization-Wide:</strong></p> <ol> <li>Select "Org-wide" tab</li> <li>Optionally add allow/deny filters for topics and tags</li> <li>Add a description explaining what this scope is for</li> </ol> <p><strong>For Project-Specific:</strong></p> <ol> <li>Select "Project" tab</li> <li>Choose a project from the searchable dropdown</li> <li>Optionally restrict to specific topics (topics from the selected project will appear as suggestions)</li> <li>Add allow/deny tags as needed</li> </ol> <p><strong>For Topic Pattern:</strong></p> <ol> <li>Select "Topic Pattern" tab</li> <li>Enter a pattern using <code>*</code> and <code>**</code> wildcards</li> <li>Add allow/deny filters for fine-grained control</li> </ol> <h3>Step 5: Add Multiple Scopes (Optional)</h3> <p>Click <strong>"+ Add Scope"</strong> again to add additional scope rules. Remember, the key will have access to the union of all scopes.</p> <h3>Step 6: Review and Generate</h3> <p>Review your scope configuration. Once satisfied, click <strong>"Generate Key"</strong>.</p> <p><strong>Important:</strong> Copy your API key immediately. It will only be shown once for security reasons.</p> <h2>Common Patterns and Examples</h2> <h3>Read-Only Documentation Access</h3> <pre><code>Type: Topic Pattern Pattern: **/docs/** Allow Tags: public, published Deny Tags: draft, internal</code></pre> <h3>Multi-Project Development Access</h3> <pre><code>Scope 1: Type: Project Project: Frontend App Allow Tags: development, staging

Scope 2: Type: Project Project: Backend API Allow Tags: development, staging</code></pre>

<h3>Environment-Specific Access</h3> <pre><code>Type: Organization-wide Allow Tags: production Deny Topics: **/secrets/**, **/credentials/**</code></pre> <h3>Contractor Limited Access</h3> <pre><code>Type: Topic Pattern Pattern: projects/website/frontend/** Allow Tags: contractor-visible Deny Topics: **/pricing/**, **/analytics/** Expiration: 30 days</code></pre> <h2>Security Best Practices</h2> <ol> <li><strong>Principle of Least Privilege:</strong> Grant only the minimum access required</li> <li><strong>Use Project Scopes by Default:</strong> Organization-wide access should be rare</li> <li><strong>Set Short Expirations:</strong> Use 7-30 days for development, 90 days maximum for production</li> <li><strong>Rotate Keys Regularly:</strong> Use the rotation feature to update keys without downtime</li> <li><strong>Monitor Usage:</strong> Check the "Last Used" timestamp to identify unused keys</li> <li><strong>Revoke Immediately:</strong> Remove access for departed team members or compromised keys</li> <li><strong>Tag Strategically:</strong> Use tags to enable scope-based access control</li> <li><strong>Document Key Purpose:</strong> Use descriptions to track why each key exists</li> </ol> <h2>Troubleshooting Access Issues</h2> <h3>"Access Denied" Errors</h3> <p>If your API key is getting access denied errors:</p> <ol> <li>Check that the key hasn't expired</li> <li>Verify the scope includes the project/topic you're accessing</li> <li>Check deny filters - they override allow filters</li> <li>Ensure the topic/memory has the required tags if using tag filters</li> </ol> <h3>Scope Not Working as Expected</h3> <p>Common issues:</p> <ul> <li><strong>Wildcard confusion:</strong> Remember <code>*</code> is one segment, <code>**</code> is many</li> <li><strong>Filter conflicts:</strong> Deny rules take precedence over allow rules</li> <li><strong>Multiple scopes:</strong> The key gets the union of all scopes, which may be broader than expected</li> </ul> <h2>Next Steps</h2> <p>Now that you understand API key scopes, you can:</p> <ul> <li>Create keys with appropriate access levels for your integrations</li> <li>Review and tighten permissions on existing keys</li> <li>Set up automated key rotation for production systems</li> <li>Explore our <a href="/learn/tutorials">API Integration Tutorials</a></li> </ul> <blockquote> <p><strong>Pro Tip:</strong> Start with overly restrictive scopes and loosen them only when you encounter permission errors. It's easier to add permissions than to discover you've granted too much access.</p> </blockquote>