Sub-Keys (Additional Keys)

What Are Sub-Keys?

Sub-keys are secondary API keys that operate under your primary account. They provide a way to distribute API access without sharing your main API key. Key characteristics:

• Linked to your account - All sub-keys are tied to your primary API key and subscription
• Shared usage quota - API calls from sub-keys count toward your plan's limits
• Independent access control - Each sub-key can have its own scope restrictions
• Individually manageable - Create, edit, deactivate, or delete sub-keys at any time
• Distinct format - Sub-keys have a unique prefix for easy identification

Primary Key vs Sub-Keys

Why Use Sub-Keys?

Sub-keys solve several common challenges when working with APIs in teams or across multiple applications:

Team Development

Give each developer their own API key without sharing your primary credentials. If a developer leaves or a key is compromised, simply delete that specific sub-key without affecting others.

Application Isolation

Create dedicated keys for each application or service. This makes it easy to:

• Track usage per application in your analytics
• Revoke access for a single app without affecting others
• Apply different access restrictions per app

Environment Separation

Use different sub-keys for development, staging, and production environments. This prevents accidental production API calls during development and makes debugging easier.

Partner & Client Access

Provide limited API access to external partners or clients. Combine sub-keys with key scoping to restrict which APIs they can use.

Security Best Practice

Following the principle of least privilege, sub-keys allow you to distribute only the access that's needed, reducing the blast radius if any single key is compromised.

Creating Sub-Keys

You can create sub-keys through your dashboard:

1. Navigate to API Keys in your dashboard
2. In the Additional Keys section, click Create Sub-Key
3. Enter a descriptive name for the key (e.g., "Production Backend", "Dev - Sarah", "Mobile App")
4. Optionally configure access scopes to restrict which APIs the key can use
5. Click Create Sub-Key

Your new sub-key will appear in the list immediately. Copy it and store it securely - you can always view it again from the dashboard, but treat it like any sensitive credential.

Naming Requirements

• Maximum 50 characters
• Allowed characters: letters, numbers, spaces, hyphens (-), and underscores (_)
• Names must be unique within your account

Managing Sub-Keys

All sub-key management is done through the API Keys page in your dashboard.

Viewing Sub-Keys

Your sub-keys are listed in the "Additional Keys" section. Each entry shows:

• Name - The descriptive name you assigned
• Key value - The actual API key (hidden by default, click the eye icon to reveal)
• Scope description - Summary of access restrictions, if any
• Created date - When the key was created
• Status - Active or Inactive badge

Copying a Sub-Key

Click the copy icon next to any sub-key to copy it to your clipboard. A checkmark confirms the copy was successful.

Editing a Sub-Key

Click the edit icon (pencil) to modify a sub-key. You can change:

• The key's name
• Access scopes (which APIs and features are allowed/blocked)

Changes take effect immediately, though scope changes may take up to 10 minutes to fully propagate.

Deactivating a Sub-Key

You can temporarily deactivate a sub-key without deleting it. Deactivated keys:

• Cannot make API requests (receive 401 Unauthorized)
• Remain in your list and can be reactivated anytime
• Don't count toward your sub-key limit while inactive

This is useful for temporarily suspending access without losing the key's configuration.

Deleting a Sub-Key

Click the trash icon to permanently delete a sub-key. This action:

• Is immediate and irreversible
• Instantly invalidates the key for all API requests
• Frees up a slot in your sub-key limit

Sub-Key Format & Identification

Sub-keys have a distinct format that differentiates them from primary keys:

Primary Key: apv_abc123def456ghi789...
Sub-Key:     apv_sbk_xyz789abc123def456...

The apv_sbk_ prefix makes it easy to identify sub-keys in your code, logs, and configuration. This is useful for:

• Auditing which type of key made a request
• Validating key types in your application logic
• Troubleshooting authentication issues

Using Sub-Keys in Requests

Sub-keys are used exactly like primary keys - include them in the X-API-Key header:

GET /v1/weather?city=London HTTP/1.1
Host: api.apiverve.com
X-API-Key: apv_sbk_your_sub_key_here
Content-Type: application/json

Sub-Key Limits

The number of sub-keys you can create depends on your subscription plan:

Your current usage is displayed as a progress bar in the dashboard. When you reach your limit, you'll need to delete existing sub-keys or upgrade your plan to create more.

Scoping Sub-Keys

One of the most powerful features of sub-keys is the ability to restrict which APIs and features they can access. This is done through key scoping.

With scoping, you can:

• Block specific APIs - Allow access to most APIs but block certain ones
• Whitelist APIs - Block all APIs except a specific list
• Restrict VerveKit features - Control access to JSONBin, MockServer, Forms, GraphQL

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

This scope blocks all APIs except Email Validator, Weather, and Currency Converter - perfect for a production app that only needs these three APIs.

For complete details on scope configuration, see the Key Scoping documentation.

Billing & Usage

Sub-keys share your account's subscription and usage quota:

• No additional cost - Creating sub-keys doesn't increase your subscription fee
• Shared rate limits - All keys (primary + sub-keys) share your plan's rate limits
• Consolidated billing - All API calls are billed to the parent account
• Unified analytics - Usage from all keys appears in your dashboard analytics

Limitations

Be aware of these limitations when using sub-keys:

No Integration Support

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
• Pipedream

If a sub-key is used with these integrations, the request will be rejected with a 401 error.

No Key Rotation

Unlike primary keys, sub-keys cannot be rotated. If you need to change a sub-key's value, you must:

1. Create a new sub-key with the same configuration
2. Update your applications to use the new key
3. Delete the old sub-key

Cannot Create Nested Sub-Keys

Sub-keys cannot create additional sub-keys. Only your primary API key (or dashboard access) can create sub-keys.

Scope Inheritance

If your primary key has scope restrictions, sub-keys can only have equal or more restrictive scopes - they cannot access APIs that the primary key cannot access.

Best Practices

• Use descriptive names - Names like "Prod-Backend-v2" or "Dev-Sarah-Local" are much more useful than "Key1" or "Test"
• Apply least privilege - Only grant access to the APIs each key actually needs
• Separate environments - Use different sub-keys for dev, staging, and production
• Review regularly - Periodically audit your sub-keys and delete unused ones
• Document key purposes - Keep internal records of which keys are used where
• Treat as secrets - Store sub-keys securely, never commit them to version control
• Plan for rotation - Have a process for replacing compromised keys quickly

Troubleshooting

401 Unauthorized with Sub-Key

If you receive a 401 error when using a sub-key:

• Verify the key is active (not deactivated) in your dashboard
• Check that you're using the complete key including the apv_sbk_ prefix
• Ensure the key hasn't been deleted
• Confirm the parent account's subscription is active

403 Forbidden - Access Blocked

If you receive a 403 error:

• The sub-key's scope is blocking access to the requested API
• Check the key's scope configuration in the dashboard
• See Key Scoping for details on scope errors

Sub-Key Not Working with Zapier/Make

This is expected behavior. Integrations require your primary API key. Use your main apv_ key instead of a sub-key for integration platforms.

Can't Create More Sub-Keys

You've reached your plan's sub-key limit. Options:

• Delete unused sub-keys to free up slots
• Deactivate keys you're not currently using
• Upgrade your plan for a higher limit