# 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](https://docs.vendia.com/platform/vendia-mcp-server/api-connections/creating-api-connections)** - Set up your first catalog
- **[Best Practices](https://docs.vendia.com/platform/vendia-mcp-server/api-connections/best-practices)** - Optimize security and performance
- **[Troubleshooting](https://docs.vendia.com/platform/vendia-mcp-server/api-connections/troubleshooting)** - Resolve authentication issues