Authentication and Headers

Learn how to configure authentication credentials and custom headers to enable AI applications to securely interact with your APIs through Vendia MCP Gateway.

Overview

API Connections support custom HTTP headers to enable authentication and other request customization. This allows AI applications to access protected APIs while maintaining security best practices.

Authentication Methods

API Key Authentication

The most common authentication method for APIs. API keys are passed in a header with each request.

Custom Header Name Configuration

Header Name: X-API-Key

Header Value: your-api-key-here

Standard API Key Header Configuration

Header Name: API-Key

Header Value: your-api-key-here

API Key Use Cases

• Third-party services (Slack, JIRA, Snowflake)
• Internal microservices
• Public APIs with usage limits

Bearer Token Authentication

Used for OAuth 2.0, JWT tokens, and other token-based authentication schemes.

Bearer Token Header Configuration

Header Name: Authorization

Header Value: Bearer your-access-token-here

Bearer Token Use Cases

• OAuth 2.0 protected APIs
• JWT-based authentication
• Short-lived access tokens

Basic Authentication

Traditional username/password authentication encoded in Base64.

Basic Auth Header Configuration

Header Name: Authorization

Header Value: Basic base64-encoded-credentials

To create the value:

1. Combine username and password: username:password
2. Encode in Base64: dXNlcm5hbWU6cGFzc3dvcmQ=
3. Prefix with Basic followed by a space: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Basic Auth Use Cases

• Legacy APIs
• Internal systems
• Simple authentication requirements

Custom Authentication Schemes

Some APIs use custom authentication headers.

Custom Authentication Examples

Custom Token Header:

Header Name: X-Auth-Token

Header Value: your-custom-token

Service-Specific Header:

Header Name: X-Service-Key

Header Value: service-specific-credential

Custom Headers

Beyond authentication, you can add custom headers for other purposes.

Custom Request Headers

Add service-specific headers:

Header Name: X-Request-ID

Value: application/json

Security Best Practices

Use Short-Lived Tokens

Limit Credential Scope

Configure credentials with minimal necessary permissions:

• Read-only access when write is not needed
• Scoped to specific resources or endpoints
• Rate-limited to prevent abuse

Rotate Credentials Regularly

Establish a credential rotation schedule:

1. Generate new credentials
2. Update API Connection with new values
3. Revoke old credentials after transition period
4. Document rotation dates

Secure Your Vendia Account

Protect the account that stores your API credentials:

• Enable multi-factor authentication (MFA)
• Use strong, unique passwords
• Limit account access to authorized users
• Monitor account activity logs

Avoid Committing Credentials

Never commit API credentials to version control:

• Store credentials in secure vaults
• Use environment variables for local development
• Document where credentials are stored for team members

Managing Headers in the Console

Adding Headers

1. Navigate to your API Connection in the Vendia console
2. Scroll to the Headers section
3. Click Add Header
4. Enter the header name and value
5. Click Save Changes

Updating Headers

1. Locate the header you want to update
2. Click the Edit icon
3. Modify the header name or value
4. Click Save Changes

Removing Headers

1. Locate the header you want to remove
2. Click the Delete or Remove icon
3. Confirm the deletion
4. Click Save Changes

Testing Authentication

After configuring authentication, verify it works correctly:

Test with AI Application

1. Connect your AI application to the MCP server
2. Ask the AI to list available API operations
3. Request the AI to make a test API call
4. Verify the call succeeds and returns expected data

Check API Logs

Review logs from your API service to confirm:

• Requests include the authentication header
• Authentication is successful
• No authorization errors

Troubleshooting Authentication Issues

Problem: API returns 401 Unauthorized

Solutions:

• Verify the header name is correct (case-sensitive)
• Check that the credential is valid and not expired
• Ensure the credential has necessary permissions
• Test the API directly with the same credentials

Problem: API returns 403 Forbidden

Solutions:

• Verify the credential has permission to access the endpoint
• Check if the API requires additional headers or parameters
• Review API documentation for access requirements

Common Authentication Patterns

Slack API

Header Name: Authorization

Header Value: Bearer xoxb-your-slack-bot-token

GitHub API

Header Name: Authorization

Header Value: Bearer github_pat_your_personal_access_token

Stripe API

Header Name: Authorization

Header Value: Bearer sk_test_your_stripe_secret_key

Twilio API

Header Name: Authorization

Header Value: Basic base64(account_sid:auth_token)

Custom Internal API

Header Name: X-Internal-API-Key

Header Value: your-internal-service-key

Multiple Headers Example

You can add multiple headers to your API Connection:

Header 1:

Name: Authorization

Value: Bearer your-access-token

Header 2:

Name: X-Request-Source

Value: vendia-mcp-server

All headers are sent together with each API request made by AI applications.

Next Steps

• Creating API Connections - Set up your first catalog
• Best Practices - Optimize security and performance
• Troubleshooting - Resolve authentication issues