Skip to main content

Validating Credentials

Credential validation ensures your API keys and OAuth tokens are working correctly before tools use them. This guide walks through the validation process with the new streamlined interface.

Why Validate Credentials?​

After adding credentials (API key, OAuth token, etc.) to a provider, you need to verify they work. Validation:

✅ Confirms credentials are correct - No typos, valid format
✅ Tests API connectivity - Provider is reachable
✅ Checks permissions - OAuth scopes are sufficient
✅ Activates tools - Bundles become ready to use
✅ Prevents runtime errors - Catch issues before your AI tries to use tools

Without validation:

  • Tools won't appear in your AI
  • Bundles show "Setup Required" status
  • You'll discover credential issues later when tools fail

With validation:

  • All tools become immediately available
  • Bundles show "Ready - Credentials valid" status
  • Confident that everything works

The Validation Process​

Overview​

The validation flow has three clear steps, all happening in one place:

  1. Add Credential → Enter API key or complete OAuth (sidemenu stays open)
  2. Choose Validation Tool → Picker automatically opens after credential creation
  3. Validate → Run the tool to verify credentials work (results shown in sidemenu)

Credential Setup Flow

Key improvement: The credential panel stays open throughout the entire process - you won't lose your place when doing OAuth authentication!

Step 1: Add Credentials​

You can add credentials from several places:

  • Bundle Page → Click "Configure" next to a provider → Click "+ Add New Credential"
  • Provider Detail Page → Click "Add Credential"
  • Add Tool Dialog → When selecting tools, click "+ Add New Credential"

All these paths open the same credential panel on the right side of your screen.

For API Key Providers​

Example: Smartlead, OpenAI, HubSpot

  1. Credential panel opens on the right side
  2. Get your API key from the provider's website (Settings → API Keys)
  3. Paste the API key into the credential panel field
  4. (Optional) Enter a descriptive Credential Name (e.g., "Production Account")
  5. Fill any other required fields (like Instance URL for HubSpot)
  6. Click "Create Credential"

API Key Entry

Result:

  • ✅ Credential is saved successfully
  • 🎯 Validation tool picker automatically opens
  • Status shows "UNVERIFIED" until you validate

For OAuth Providers​

Example: GitHub, Slack, Sentry, Google

  1. Credential panel opens on the right side
  2. (Optional) Enter a descriptive Credential Name (e.g., "Work GitHub", "Production Sentry")
  3. Click the large blue "Connect with [Provider]" button
  4. OAuth window opens → Log in to the provider
  5. Review and approve the requested permissions (scopes)
  6. Click "Allow" or "Authorize"
  7. OAuth window closes → You return to the credential panel
  8. 🎯 Validation tool picker automatically opens

OAuth Flow

Key Feature: The credential panel automatically reopens after OAuth! You don't lose your place or have to navigate back.

Result:

  • ✅ OAuth token is saved successfully
  • 🎯 Validation tool picker is ready for you to choose a test tool
  • Status shows "UNVERIFIED" until you validate

For Public APIs (No Auth)​

Example: OpenWeatherMap free tier, NASA API

These providers don't require authentication. Credentials are automatically verified when you add tools that use them.

Step 2: Choose a Validation Tool​

After creating your credential, the validation tool picker automatically opens:

Validation Tool Picker

What is a Validation Tool?​

A validation tool is a simple, safe tool from the provider that tests your credentials by making a real API call.

Good validation tools:

  • ✅ Read-only operations (list, get, fetch)
  • ✅ No required parameters
  • ✅ Quick to execute (< 2 seconds)
  • ✅ Don't modify data

Examples:

  • get_user - Gets your account information
  • list_campaigns - Lists your campaigns
  • analytics_links - Gets analytics data
  • get_profile - Retrieves profile details

How to Choose​

  1. Look for "Recommended" badges - These tools are pre-selected as safe and simple
  2. Read the tool description - Understand what it does
  3. Check required parameters - Tools with no parameters are fastest to validate
  4. Click "Use as validator" on your chosen tool

Tool Selected

Result: The picker closes and you'll see the "Validate Now" button ready!

If You're Not Sure Which Tool to Pick​

Rule of thumb: Pick the first tool marked "Recommended" that:

  • Has a name like get_*, list_*, or fetch_*
  • Has a description mentioning "user", "account", "profile", or "info"
  • Shows "No parameters required"

You can always change the validation tool later.

Step 3: Validate Your Credentials​

After selecting a validation tool, you'll see:

Validate Now

Understanding the Status Display​

Before validation:

  • Status badge shows "UNVERIFIED" (yellow/amber)
  • Large green "Validate Now" button is prominent
  • Tool name is displayed (e.g., "Using tool: get_user")

Running Validation​

  1. Click the large green "Validate Now" button
  2. Wait 1-3 seconds - The tool makes a real API call
  3. Watch for the result:

✅ Success:

  • Status changes to "VERIFIED" (green checkmark)
  • Success message appears
  • Credential is now ready to use!
  • Panel may close automatically

❌ Failed:

  • Error message appears explaining what went wrong
  • Common issues:
    • Invalid API key (typo, expired)
    • Insufficient permissions (OAuth scopes)
    • Network connectivity issues
    • Provider service outage

If Validation Fails​

For API Keys:

  1. Double-check for typos or extra spaces
  2. Verify the API key is active in the provider's dashboard
  3. Check the key has the required permissions
  4. Try generating a new API key

For OAuth:

  1. Click "Connect with [Provider]" again to re-authenticate
  2. Make sure you approve ALL requested permissions
  3. Check you're logging in with the correct account
  4. Verify your account has the necessary role/access level

Still failing? See Troubleshooting Connectivity for detailed debugging steps.

Validation Tool Parameters​

Some validation tools require input parameters. For example:

  • get_campaign needs a campaign_id
  • fetch_project needs a project_id

If Your Validation Tool Needs Parameters:​

  1. After selecting the tool, you'll see a "Validation Parameters" section
  2. Click "Configure" to open the parameter form
  3. Fill in the required values (you can usually find these in the provider's dashboard)
  4. Click "Save"
  5. Now click "Validate Now" to run the test

Tip: Choose tools without parameters when possible - they're faster to validate!

After Successful Validation​

Once validation succeeds:

✅ Credential Status Changes to "VERIFIED"

  • Green checkmark badge appears
  • Status shows "VERIFIED" ✓
  • Timestamp shows when validation occurred
  • Credential is now functional

📦 Bundle Page Updates:

  • Provider now shows "Verified" badge (green)
  • "Configuration Required" warning may disappear if all providers are configured
  • Bundle becomes ready to use

🎯 Tools Become Available:

  • All tools from this provider are now accessible
  • Your AI can immediately start using these tools
  • Bundle shows "Ready" status

What You Can Do Next​

From the credential panel:

  • "Re-validate" - Test the credential again with the same tool
  • "Change Tool" - Select a different validation tool
  • "Close" - Return to your bundle page

From the bundle page:

  • "Edit" - Update the credential name or settings
  • "Change" - Swap to a different credential
  • "Unbind" - Remove the credential from this bundle

Credential Status Reference​

Status Badges Explained​

🟡 UNVERIFIED (Yellow/Amber)

  • What it means: Credential is saved but not tested
  • Next action: Choose a validation tool and validate
  • Tools status: Hidden until verified
  • Button: Large "Validate Now" (after selecting tool)

🟢 VERIFIED (Green)

  • What it means: Credential tested successfully
  • Next action: None required - ready to use!
  • Tools status: All tools available
  • Buttons: "Re-validate" (optional), "Change Tool" (optional)

🔴 ERROR (Red)

  • What it means: Validation failed
  • Next action: Fix the credential or choose a different validation tool
  • Tools status: Unavailable until fixed
  • Button: "Retry Validation"

Common Validation Scenarios​

  • Reliable - If they work, your credentials are valid

How to Choose​

  1. After adding credential, click "Choose Validation Tool"
  2. Modal opens showing available tools
  3. Look for tools with names like:
    • list_* - List resources
    • get_account_* - Account info
    • verify_* - Verification endpoints
    • test_* - Test endpoints
  4. Hover over a tool to see its description
  5. Click "Use as validator" on a tool
  6. Tool is selected and modal closes

Tips:

  • Choose the simplest tool (fewest required arguments)
  • Prefer list or get operations over create or delete
  • If unsure, pick the first one that looks safe
  • You can change the tool later if needed

Tools with Arguments​

Some validation tools need input parameters:

Example: get_campaign_stats requires campaign_id

What you'll see:

  • After selecting tool, "Validation Parameters" section appears
  • Shows fields the tool needs
  • Mark required fields with *

What to do:

  1. Click "Configure" to expand parameter inputs
  2. Fill in required fields
  3. Arguments are saved for future validations
  4. Click "VALIDATE NOW"

Step 4: Run Validation​

The Big Green Button​

Once a validation tool is selected, you'll see:

VALIDATE NOW (large, bold, green button, center of card)

This button:

  • Is impossible to miss (that's the point!)
  • Runs the validation tool with your credentials
  • Shows "VALIDATING..." with spinner while running
  • Updates status based on result

What Happens During Validation​

When you click "VALIDATE NOW":

  1. Tool Executes (1-3 seconds usually)

    • Makes real API call to provider
    • Uses your credential for authentication
    • Runs the validation tool you selected

  2. Result Displayed

    • Success: Status changes to ✅ VERIFIED (green)
    • Failure: Status changes to ❌ ERROR (red)
    • Validation message appears below status

  3. Page Updates

    • Provider status updates across entire page
    • Bundle readiness recalculates
    • "X credentials need verification" counter updates
    • All status badges refresh

Success Response​

What you'll see:

VERIFIED
Just validated

Validation Tool: List Campaigns

[Re-validate] [Change Tool]

Below, a green success box:

Successfully Validated!

Campaign data retrieved successfully. Found 3 active campaigns.

Last validated: Just now

What this means:

  • Credentials are correct
  • API is reachable
  • Permissions are sufficient
  • All tools are now available

Next steps:

  • Nothing! You're done.
  • Go to bundles to see them show "Ready - Credentials valid"
  • Add bundles to your AI

Failure Response​

What you'll see:

ERROR
Validation failed

Validation Tool: List Campaigns

[VALIDATE NOW] (to try again)

Below, a red error box:

Validation Failed

Authentication failed: Invalid API key

The API key provided does not match any active key in your Smartlead account.

Please verify:
• The API key is correct
• The key hasn't been revoked
• You're using the right Smartlead account

What this means:

  • Credentials are invalid or incorrect
  • API call failed
  • Tools won't work

Next steps: See Troubleshooting below

Understanding Validation Results​

Common Success Messages​

Credential verified:

Successfully Validated!
Credential is working correctly
Last validated: Just now

Data retrieved:

Successfully Validated!
Retrieved 3 campaigns from your account
Last validated: Just now

Account info confirmed:

Successfully Validated!
Connected to account: tony@example.com
Last validated: Just now

Common Error Messages​

Invalid API Key​

Authentication failed: Invalid API key

The API key provided is not valid.

Causes:

  • Typo when pasting key
  • Key was deleted from provider
  • Key was regenerated
  • Wrong provider account

Fix:

  1. Go to provider's dashboard
  2. Generate new API key
  3. Click "Edit" on credential
  4. Paste new key
  5. Click "Save"
  6. Click "VALIDATE NOW" again

Insufficient Permissions​

Authorization failed: Missing required scope

This tool requires 'read:campaigns' scope but your token only has 'read:profile'.

Causes:

  • OAuth: Didn't grant enough permissions
  • API Key: Key doesn't have right access level

Fix for OAuth:

  1. Click "Edit" on credential
  2. Click "Re-authorize"
  3. Grant additional scopes when prompted
  4. Validation runs automatically

Fix for API Key:

  1. Go to provider's dashboard
  2. Create new key with higher permissions
  3. Update credential with new key
  4. Validate again

Provider Down​

Connection failed: Service unavailable

Unable to reach Smartlead API. The service may be temporarily down.

Causes:

  • Provider's API is down
  • Network issues
  • Rate limiting

Fix:

  1. Check provider's status page
  2. Wait 5-10 minutes
  3. Try validation again
  4. If persistent, contact support

Invalid Input​

Validation failed: Missing required argument

Tool 'get_campaign_stats' requires 'campaign_id' but none was provided.

Causes:

  • Validation tool needs arguments
  • Required field wasn't filled

Fix:

  1. Click "Configure" in Validation Parameters section
  2. Fill required fields
  3. Validate again

After Validation​

Verified Credentials Unlock Everything​

Once validated, credentials activate:

Bundles:

  • "Setup Required" → "Ready - Credentials valid" (if all providers now verified)
  • Ready to use in AI

Tools:

  • Appear in your AI's available tools
  • Can be executed in Bundle Studio
  • Shown as "Ready" in dashboard

Provider Status:

  • Changes from "Unverified" to "Connected"
  • Green checkmark displayed
  • "0 credentials need verification"

Re-validating Credentials​

You can re-validate anytime:

When to re-validate:

  • After updating credential
  • Provider had an outage (to confirm it's back)
  • Tools started failing (to diagnose)
  • Just to be sure

How to re-validate:

  1. Go to provider → Find credential
  2. Click "Re-validate" button
  3. Validation runs again
  4. Status updates based on result

Re-validation is instant - no need to re-enter credentials.

Changing Validation Tool​

If one validation tool doesn't work, try another:

Reasons to change:

  • Current tool requires arguments you don't have
  • Current tool keeps failing
  • Want to test a different endpoint

How to change:

  1. Click "Change Tool" (small link below validate button)
  2. Select different tool from list
  3. Click "Use as validator"
  4. New tool is set
  5. Click "VALIDATE NOW" to test

Troubleshooting​

"Choose Validation Tool" button does nothing​

Cause: No tools available for this provider yet.

Solution:

  1. Check if provider is an MCP provider
  2. If yes, discover tools first:
    • Go to provider page
    • Scroll to "Available Tools"
    • Click "Discover Tools"
    • Wait for discovery to complete
    • Return to credentials section
    • Validation tools now available

Validation hangs on "VALIDATING..."​

Cause: Provider API is slow or timing out.

Solution:

  1. Wait up to 30 seconds
  2. If still stuck, refresh the page
  3. Try a different validation tool
  4. Check provider's status page

"Validation succeeded but tools still not showing"​

Cause: Bundle not refreshed or other providers still need credentials.

Solution:

  1. Check bundle page
  2. Look for "Bundle Readiness" section
  3. Verify all providers show green checkmark
  4. If bundle still shows "Setup Required", check other provider requirements
  5. Refresh browser if status looks correct

"Tool requires arguments but I don't have them"​

Example: get_campaign_stats needs campaign_id but you don't know your campaign IDs.

Solution:

  1. Click "Change Tool"
  2. Select a simpler tool like list_campaigns
  3. Validate with that tool instead
  4. Once validated, use list_campaigns in Bundle Studio to get IDs
  5. Then you can test get_campaign_stats if needed

"Credential was working, now shows ERROR"​

Causes:

  • API key was rotated/regenerated
  • OAuth token expired and auto-refresh failed
  • Provider revoked access
  • Account was suspended

Solution:

  1. Try re-validating first (might be temporary)
  2. If still fails, check error message
  3. If "Invalid API key":
    • Edit credential
    • Update with new key
    • Validate again
  4. If "Token expired":
    • Click "Re-authorize"
    • Complete OAuth flow
    • Validates automatically

Best Practices​

Validate Immediately​

Validate credentials as soon as you add them. Don't wait until you need to use tools.

Choose Simple Validation Tools​

Pick list_* or get_account_* tools. Avoid tools that create, delete, or modify data.

Test with Real Accounts​

Use actual production or development credentials. Test accounts might have limited data or restricted access.

Keep Credentials Up to Date​

If you regenerate API keys or revoke OAuth access, update credentials in MCPBundles immediately.

Re-validate After Issues​

If tools start failing, re-validate to confirm credentials still work.

Don't Skip Validation​

Even if you're confident credentials are correct, always validate. It catches issues early.

Don't Use Destructive Validation Tools​

Never pick tools like delete_* or clear_* as validators. Stick to read-only operations.

Visual Guide to Status Flow​

┌─────────────────────────────────────────────────────────────┐
│ 1. ADD CREDENTIAL                                           │
│                                                             │
│ [API Key Input Field]                                       │
│ [Create Credential Button]                                  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ UNVERIFIED - CHOOSE A VALIDATION TOOL                       │
│ Select a tool to test this credential                       │
│                                                             │
│ [ Choose Validation Tool ]  ← Click this                    │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ VALIDATION TOOL PICKER                                      │
│                                                             │
│ • list_campaigns       [Use as validator]                   │
│ • get_account_info     [Use as validator]  ← Click one      │
│ • list_contacts        [Use as validator]                   │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ UNVERIFIED - READY TO VALIDATE                              │
│ Click validate to test this credential                      │
│                                                             │
│ Validation Tool: List Campaigns                             │
│                                                             │
│ [VALIDATE NOW]  ← Click this big green button               │
└─────────────────────────────────────────────────────────────┘
                          ↓
                   (Running...)
                          ↓
          ┌───────────────┴───────────────┐
          │                               │
       SUCCESS                         FAILURE
          │                               │
          ↓                               ↓
┌─────────────────────────┐  ┌─────────────────────────┐
│ VERIFIED                │  │ ERROR                    │
│ Just validated          │  │ Validation failed        │
│                         │  │                          │
│ Successfully            │  │ Validation Failed        │
│ Validated!              │  │                          │
│                         │  │ [Error details here]     │
│ Credential is working   │  │                          │
│ correctly               │  │ [VALIDATE NOW]           │
│                         │  │ (try again)              │
│ [Re-validate]           │  └─────────────────────────┘
│ [Change Tool]           │
└─────────────────────────┘

What's Next?​

After validating credentials:

1. Enable Bundles​

Go to Dashboard → Bundles and enable bundles that use your verified providers.

2. Test in Bundle Studio​

Use Bundle Studio to test tools interactively before adding to your AI.

3. Add to Your AI​

Follow integration guides to connect bundles to ChatGPT, Claude, Cursor, etc.

4. Monitor Status​

Check Dashboard → Providers regularly to ensure credentials stay verified.

Need Help?​

  • Email: help@mcpbundles.com
  • Docs: Browse sidebar for more guides
  • Support: Contact us with validation issues

Validation is quick and ensures everything works. Happy validating!