API Key Scoping

Overview

Key scoping provides granular access control over your APIVerve resources. You can:

• Block specific APIs - Prevent access to certain APIs while allowing others
• Allow only specific APIs - Create keys that can only access a whitelist of APIs
• Restrict VerveKit features - Control access to JSONBin, MockServer, Forms, and GraphQL
• Create sub-keys - Generate additional keys with independent scopes for team members or applications

Scoping works on both your primary API key and any sub-keys you create. Each key can have its own independent scope configuration.

Scope Types

There are two main categories of scopes you can configure:

API Scopes

Control access to individual APIs in the APIVerve marketplace. You can either block specific APIs or block all APIs except those you explicitly allow.

VerveKit Feature Scopes

Control access to VerveKit developer tools:

Configuring Scopes

You can configure scopes through the dashboard or programmatically via API.

Using the Dashboard

1. Navigate to API Keys in your dashboard
2. Click the Scope button on your primary key or any sub-key
3. Use the APIs section to search and select APIs to block
4. Use the VerveKit section to toggle feature access
5. Click Save Changes to apply the scope

Scope Format

Scopes are stored as an array of strings. Understanding the format helps when working with the API:

["weather", "news", "stocks"]

This blocks only the Weather, News, and Stocks APIs. All other APIs remain accessible.

["*apis", "!emailvalidator", "!qrcodegenerator", "!weather"]

The *apis wildcard blocks all APIs. The ! prefix creates exceptions, so only Email Validator, QR Code Generator, and Weather APIs are accessible.

["*vervekit"]

["*apis", "!weather", "!news", "jsonbin", "mock"]

This allows only Weather and News APIs, while blocking JSONBin and MockServer features.

null

Setting the scope to null or an empty array [] grants full access to all APIs and features.

Sub-Keys

Sub-keys are additional API keys linked to your account. They share your subscription's usage quota but can have independent scope restrictions. This is ideal for:

• Team members - Give developers access to only the APIs they need
• Applications - Create dedicated keys for each app with minimal permissions
• Environments - Separate keys for development, staging, and production
• Clients - Provide limited access to external parties

Creating Sub-Keys

1. Go to API Keys in your dashboard
2. Click Create Sub-Key
3. Enter a descriptive name (e.g., "Production Server", "Mobile App", "Partner Integration")
4. Configure the scope to restrict access as needed
5. Click Create

Sub-Key Format

Sub-keys have a distinct format to differentiate them from primary keys:

Sub-Key Billing

Sub-keys share your account's usage quota. All API calls made with sub-keys count toward your plan's limits and are billed to the parent account. This means:

• No additional subscription costs for sub-keys
• All usage is consolidated in your analytics
• Rate limits are shared across all keys

Managing Scopes via API

You can programmatically manage key scopes using the Dashboard API.

PUT /api/apikeys/{userId}/restrictions
Content-Type: application/json
Authorization: Bearer {session_token}

{
  "blockScope": ["weather", "news", "*vervekit"]
}

POST /api/apikeys/{userId}/subkeys
Content-Type: application/json
Authorization: Bearer {session_token}

{
  "name": "Production Server",
  "blockScope": ["*apis", "!emailvalidator", "!weather"]
}

PUT /api/apikeys/{userId}/subkeys/{subKeyId}
Content-Type: application/json
Authorization: Bearer {session_token}

{
  "name": "Production Server",
  "blockScope": ["*apis", "!emailvalidator", "!weather", "!qrcodegenerator"]
}

Scope Enforcement

When a key attempts to access a blocked API or feature, the request is rejected with a 403 Forbidden response:

{
  "status": "error",
  "error": "Access to weather is blocked for this API key",
  "data": null
}

The error message clearly indicates which API or feature was blocked, making it easy to diagnose scope issues.

Limitations

Be aware of these limitations when using key scoping:

Integration Restrictions

Sub-keys cannot be used with third-party integrations. The following platforms require your primary API key:

• Zapier
• Make (Integromat)
• Pabbly Connect
• Power Automate
• n8n

Scope Granularity

• API-level only - Scopes work at the API level, not individual endpoints
• No HTTP method restrictions - Cannot restrict GET vs POST for a given API
• No IP-based restrictions - Scopes don't support geographic or IP filtering
• No time-based restrictions - Cannot set time windows for access

Sub-Key Naming

• Maximum 50 characters
• Only letters, numbers, spaces, hyphens, and underscores allowed
• Names must be unique within your account

Common Use Cases

Development Team Access

Create sub-keys for each developer with access only to APIs they're working on:

["*apis", "!qrcodegenerator", "!imageresizer", "!colorpalette"]

Production Application

Create a minimal-permission key for your production app:

["*apis", "!emailvalidator", "!weather", "*vervekit"]

This key can only use Email Validator and Weather APIs, with all VerveKit features disabled.

Partner Integration

Provide a limited key to external partners:

["*apis", "!currencyconverter"]

Partners can only access the Currency Converter API, nothing else.

Testing Environment

Block production-only APIs in your test environment:

["emailsender", "smssender", "paymentprocessor"]

This prevents accidentally triggering real emails, SMS, or payments during testing.

Best Practices

• Principle of Least Privilege - Always grant the minimum access required. Start with a restrictive scope and add permissions as needed.
• Use Descriptive Names - Name sub-keys clearly (e.g., "Production-Backend", "Dev-John", "Partner-AcmeCorp") so you can easily identify their purpose.
• Audit Regularly - Review your sub-keys and their scopes periodically. Remove unused keys and tighten scopes that are too permissive.
• Separate Environments - Use different sub-keys for development, staging, and production to prevent cross-environment issues.
• Monitor Usage - Check your analytics dashboard to see which APIs each key is accessing.
• Document Your Scopes - Keep internal documentation of which keys have which scopes, especially when working in teams.