# Personal Connectors Authentication Guide

div
strong
🔨 In Development
 — This section is still being developed and may change.


This guide covers how to authenticate and secure your personal connector configurations.

## Authentication Methods

Personal connectors support multiple authentication methods depending on the service:

### API Keys

Most services use API keys for authentication.

**Example (ClickUp):**


```json
{
  "credentials": {
    "apiKey": "pk_12345678_ABCDEFGHIJKLMNOP"
  }
}
```

**Example (GitHub):**


```json
{
  "credentials": {
    "token": "ghp_abcdefghijklmnopqrstuvwxyz123456"
  }
}
```

### OAuth 2.0

Some services require OAuth 2.0 authentication (coming soon).

**Example (Microsoft Teams):**


```json
{
  "credentials": {
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "refreshToken": "0.AXEA...",
    "expiresAt": "2025-10-08T10:00:00Z"
  }
}
```

### Username & Password

Basic authentication for certain services.

**Example (Jira):**


```json
{
  "credentials": {
    "email": "user@example.com",
    "apiToken": "ATATT3xFfGF0..."
  }
}
```

### Custom Authentication

For custom MCP servers, you can provide any credential format:


```json
{
  "credentials": {
    "customKey": "value",
    "anotherKey": "value"
  }
}
```

## Credential Validation

When you create or update a configuration, Freddy **automatically validates** your credentials:

### Validation Process

1. **Format Check** - Ensures credentials are properly formatted
2. **Live Test** - Connects to the service and tests authentication
3. **Permission Check** - Verifies credentials have required permissions (where applicable)


### Success Response

If credentials are valid:


```json
{
  "id": "pconf_abc123",
  "connectorId": "github",
  "name": "My GitHub",
  "healthStatus": "healthy",
  "enabled": true,
  ...
}
```

### Error Response

If credentials are invalid:


```json
{
  "error": {
    "message": "Failed to validate credentials for github: 401 Unauthorized - Invalid token. Please check your credentials and try again.",
    "type": "validation_error",
    "code": "invalid_credentials"
  }
}
```

**Common error messages:**

- `Invalid token` - Token is incorrect or expired
- `Insufficient permissions` - Token lacks required scopes
- `Server unreachable` - Service is down or URL is incorrect
- `Authentication failed` - Username/password is wrong


## Obtaining Credentials

### GitHub Personal Access Token

1. Go to [GitHub Settings → Developer Settings → Personal Access Tokens](https://github.com/settings/tokens)
2. Click **"Generate new token (classic)"**
3. Give your token a descriptive name (e.g., "Freddy AI Integration")
4. Select scopes:
  - ✅ `repo` - Full control of private repositories
  - ✅ `read:org` - Read organization data
  - ✅ `workflow` - Update GitHub Actions workflows
5. Click **"Generate token"**
6. **Copy the token immediately** (you won't see it again)


**Token format:** `ghp_` followed by 36 characters

### ClickUp API Token

1. Go to [ClickUp Settings → Apps](https://app.clickup.com/settings/apps)
2. Scroll to **"API Token"** section
3. Click **"Generate"** (or **"Regenerate"** if you already have one)
4. Copy your API token


**Token format:** `pk_` followed by numbers and letters

### Jira API Token

1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **"Create API token"**
3. Give it a label (e.g., "Freddy AI")
4. Click **"Create"**
5. Copy the token


**Note:** You'll also need your Atlassian account email address.

### Microsoft Teams (OAuth)

OAuth integration for Teams is coming soon. You'll be able to authenticate through a web flow.

## Security Best Practices

### 1. Use Environment Variables

Never hardcode credentials in your application:


```bash
# .env file
GITHUB_TOKEN=ghp_your_token_here
CLICKUP_API_KEY=pk_your_key_here
```


```python
import os

credentials = {
    "token": os.getenv("GITHUB_TOKEN")
}
```

### 2. Use Minimal Permissions

Only grant the permissions your integration needs:

**GitHub:**

- ❌ Don't use: `admin:org`, `delete_repo`
- ✅ Use: `repo`, `read:org`


**ClickUp:**

- Request only the workspace access you need


### 3. Rotate Credentials Regularly

Update your credentials periodically:


```bash
# Update credentials via API
curl -X PATCH https://api.freddy.aitronos.com/v1/personal-connectors/configurations/{config_id} \
  -H "api-key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "token": "ghp_new_token_here"
    }
  }'
```

### 4. Monitor Usage

Check your connector usage regularly:


```bash
curl https://api.freddy.aitronos.com/v1/personal-connectors/configurations/{config_id}/usage \
  -H "api-key: $FREDDY_API_KEY"
```

### 5. Revoke Unused Connectors

Delete configurations you no longer use:


```bash
curl -X DELETE https://api.freddy.aitronos.com/v1/personal-connectors/configurations/{config_id} \
  -H "api-key: $FREDDY_API_KEY"
```

## Credential Storage

### Encryption

All credentials are **encrypted at rest** using Fernet symmetric encryption:

- ✅ Credentials encrypted before database storage
- ✅ Decrypted only when needed for API calls
- ✅ Never returned in API responses
- ✅ Encrypted in logs and audit trails


### Access Control

Credentials are scoped to your user account or API key:

- ✅ Only you can access your credentials
- ✅ Other users cannot see your configurations
- ✅ Organization admins cannot view credentials
- ✅ Freddy staff cannot access credentials


### Audit Logging

All credential operations are logged:

- ✅ Configuration creation
- ✅ Credential updates
- ✅ Tool executions
- ✅ Failed authentication attempts


## Troubleshooting

### "Invalid credentials" Error

**Problem:** Credentials are rejected during validation

**Solutions:**

1. **Check token format** - Ensure you copied the entire token
2. **Verify token is active** - Check if token was revoked
3. **Check permissions** - Ensure token has required scopes
4. **Test manually** - Try using the token directly with the service API


**Example (GitHub):**


```bash
# Test your GitHub token
curl -H "Authorization: token ghp_your_token" https://api.github.com/user
```

### "Server unreachable" Error

**Problem:** Cannot connect to the MCP server

**Solutions:**

1. **Check service status** - Is the service down?
2. **Verify URL** - Is the server URL correct?
3. **Check network** - Are you behind a firewall?
4. **Try later** - Service might be temporarily unavailable


### "Insufficient permissions" Error

**Problem:** Token lacks required permissions

**Solutions:**

1. **Update token scopes** - Add missing permissions
2. **Generate new token** - Create token with correct scopes
3. **Check service settings** - Verify account has access


### Configuration Shows "Unhealthy"

**Problem:** Configuration created but marked unhealthy

**Solutions:**

1. **Check last error** - View the `lastError` field
2. **Test connection** - Use the `/test` endpoint
3. **Refresh tools** - Try the `/refresh` endpoint
4. **Update credentials** - Credentials may have expired



```bash
# Check configuration status
curl https://api.freddy.aitronos.com/v1/personal-connectors/configurations/{config_id} \
  -H "api-key: $FREDDY_API_KEY"

# Test connection
curl -X POST https://api.freddy.aitronos.com/v1/personal-connectors/configurations/{config_id}/test \
  -H "api-key: $FREDDY_API_KEY"
```

## Next Steps

- [Set up specific connectors](/docs/documentation/personal-connectors/connectors/overview)
- [Use connectors with AI assistants](/docs/documentation/personal-connectors/usage)
- [Monitor usage and billing](/docs/documentation/personal-connectors/billing)
- [API Reference](/docs/api-reference/personal-connectors/configurations/create)