Skip to content
/
Authentication
Last updated

Personal Connectors Authentication Guide

🔨 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):

{
  "credentials": {
    "apiKey": "pk_12345678_ABCDEFGHIJKLMNOP"
  }
}

Example (GitHub):

{
  "credentials": {
    "token": "ghp_abcdefghijklmnopqrstuvwxyz123456"
  }
}

OAuth 2.0

Some services require OAuth 2.0 authentication (coming soon).

Example (Microsoft Teams):

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

Username & Password

Basic authentication for certain services.

Example (Jira):

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

Custom Authentication

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

{
  "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:

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

Error Response

If credentials are invalid:

{
  "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
  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
  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
  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:

# .env file
GITHUB_TOKEN=ghp_your_token_here
CLICKUP_API_KEY=pk_your_key_here
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:

# 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:

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:

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):

# 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
# 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

Previous page
Next page