> ## Documentation Index
> Fetch the complete documentation index at: https://auk.mamahuhu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Configure authentication for Git synchronization

## Authentication Methods

Auk supports multiple authentication methods for Git synchronization:

<CardGroup cols={2}>
  <Card title="SSH Keys" icon="key">
    Most secure and convenient - no password needed
  </Card>

  <Card title="HTTPS + Token" icon="lock">
    Works everywhere, including corporate firewalls
  </Card>

  <Card title="OAuth" icon="shield-check">
    One-click authentication (coming soon)
  </Card>

  <Card title="Deploy Keys" icon="server">
    Read-only or limited access for specific repositories
  </Card>
</CardGroup>

## SSH Key Authentication

### Setup SSH Keys

<Steps>
  <Step title="Generate SSH Key Pair">
    ```bash theme={null}
    # Generate Ed25519 key (recommended)
    ssh-keygen -t ed25519 -C "your_email@example.com"

    # Or RSA key (if Ed25519 not supported)
    ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
    ```

    When prompted:

    * **File location**: Press Enter for default (`~/.ssh/id_ed25519`)
    * **Passphrase**: Optional but recommended for security
  </Step>

  <Step title="Start SSH Agent">
    ```bash theme={null}
    # Start the SSH agent
    eval "$(ssh-agent -s)"

    # Add your SSH key
    ssh-add ~/.ssh/id_ed25519
    ```

    For macOS, add to `~/.ssh/config`:

    ```
    Host *
      AddKeysToAgent yes
      UseKeychain yes
      IdentityFile ~/.ssh/id_ed25519
    ```
  </Step>

  <Step title="Copy Public Key">
    ```bash theme={null}
    # macOS
    pbcopy < ~/.ssh/id_ed25519.pub

    # Linux (requires xclip)
    xclip -sel clip < ~/.ssh/id_ed25519.pub

    # Windows (Git Bash)
    cat ~/.ssh/id_ed25519.pub | clip

    # Or just display it
    cat ~/.ssh/id_ed25519.pub
    ```
  </Step>

  <Step title="Add to Git Service">
    Add the public key to your Git service (see platform-specific instructions below)
  </Step>
</Steps>

### Platform-Specific Setup

<Tabs>
  <Tab title="GitHub">
    1. Go to [github.com/settings/keys](https://github.com/settings/keys)
    2. Click "New SSH key"
    3. Enter a title: `Auk on MacBook Pro`
    4. Paste your public key
    5. Click "Add SSH key"

    **Test connection:**

    ```bash theme={null}
    ssh -T git@github.com
    # You should see: "Hi username! You've successfully authenticated..."
    ```

    **Repository URL format:**

    ```
    git@github.com:username/repository.git
    ```
  </Tab>

  <Tab title="GitLab">
    1. Go to [gitlab.com/-/profile/keys](https://gitlab.com/-/profile/keys)
    2. Paste your public key
    3. Enter a title: `Auk on MacBook Pro`
    4. Set expiration date (optional)
    5. Click "Add key"

    **Test connection:**

    ```bash theme={null}
    ssh -T git@gitlab.com
    # You should see: "Welcome to GitLab, @username!"
    ```

    **Repository URL format:**

    ```
    git@gitlab.com:username/repository.git
    ```
  </Tab>

  <Tab title="Gitee">
    1. 访问 [gitee.com/profile/sshkeys](https://gitee.com/profile/sshkeys)
    2. 点击 "添加公钥"
    3. 输入标题：`Auk on MacBook Pro`
    4. 粘贴公钥内容
    5. 点击 "确定"

    **测试连接:**

    ```bash theme={null}
    ssh -T git@gitee.com
    # 应该看到: "Hi username! You've successfully authenticated..."
    ```

    **仓库 URL 格式:**

    ```
    git@gitee.com:username/repository.git
    ```
  </Tab>

  <Tab title="Self-Hosted">
    For self-hosted Git servers:

    1. Add public key to `~/.ssh/authorized_keys` on server
    2. Or use your Git server's web interface

    **Test connection:**

    ```bash theme={null}
    ssh -T git@your-git-server.com
    ```

    **Repository URL format:**

    ```
    git@your-git-server.com:path/to/repository.git
    ```
  </Tab>
</Tabs>

### SSH Key Management

#### Multiple SSH Keys

If you have multiple Git accounts:

```bash theme={null}
# ~/.ssh/config
Host github.com-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work

Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal
```

Use in Auk:

```
git@github.com-work:company/api-collections.git
git@github.com-personal:username/personal-apis.git
```

#### SSH Key with Passphrase

If you set a passphrase, you'll need to enter it when adding the key:

```bash theme={null}
# Add key with passphrase
ssh-add ~/.ssh/id_ed25519

# macOS: Store passphrase in Keychain
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
```

## HTTPS Authentication

### Personal Access Token

<Tabs>
  <Tab title="GitHub">
    **Create Token:**

    1. Go to [github.com/settings/tokens](https://github.com/settings/tokens)
    2. Click "Generate new token" → "Generate new token (classic)"
    3. Enter note: `Auk Git Sync`
    4. Select scopes:
       * ✅ `repo` (Full control of private repositories)
    5. Click "Generate token"
    6. **Copy token immediately** (you won't see it again)

    **Use in Auk:**

    ```
    https://ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@github.com/username/repository.git
    ```

    Or use Git credential helper:

    ```bash theme={null}
    git config --global credential.helper store
    ```
  </Tab>

  <Tab title="GitLab">
    **Create Token:**

    1. Go to [gitlab.com/-/profile/personal\_access\_tokens](https://gitlab.com/-/profile/personal_access_tokens)
    2. Enter name: `Auk Git Sync`
    3. Set expiration date (optional)
    4. Select scopes:
       * ✅ `read_repository`
       * ✅ `write_repository`
    5. Click "Create personal access token"
    6. **Copy token immediately**

    **Use in Auk:**

    ```
    https://oauth2:glpat-xxxxxxxxxxxxxxxxxxxx@gitlab.com/username/repository.git
    ```
  </Tab>

  <Tab title="Gitee">
    **创建令牌:**

    1. 访问 [gitee.com/profile/personal\_access\_tokens](https://gitee.com/profile/personal_access_tokens)
    2. 点击 "生成新令牌"
    3. 输入描述：`Auk Git 同步`
    4. 选择权限：
       * ✅ `projects` (仓库权限)
    5. 点击 "提交"
    6. **立即复制令牌**

    **在 Auk 中使用:**

    ```
    https://username:token@gitee.com/username/repository.git
    ```
  </Tab>
</Tabs>

### Credential Storage

Store credentials securely:

<Tabs>
  <Tab title="macOS">
    Use macOS Keychain:

    ```bash theme={null}
    git config --global credential.helper osxkeychain
    ```

    First time you push/pull, enter your token as the password. macOS will store it securely.
  </Tab>

  <Tab title="Windows">
    Use Windows Credential Manager:

    ```bash theme={null}
    git config --global credential.helper wincred
    ```

    Or use Git Credential Manager:

    ```bash theme={null}
    git config --global credential.helper manager
    ```
  </Tab>

  <Tab title="Linux">
    Use libsecret:

    ```bash theme={null}
    git config --global credential.helper /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret
    ```

    Or cache credentials temporarily:

    ```bash theme={null}
    # Cache for 1 hour
    git config --global credential.helper 'cache --timeout=3600'
    ```
  </Tab>
</Tabs>

## Deploy Keys

For read-only or repository-specific access:

### GitHub Deploy Keys

<Steps>
  <Step title="Generate Deploy Key">
    ```bash theme={null}
    ssh-keygen -t ed25519 -C "auk-deploy-key" -f ~/.ssh/auk_deploy_key
    ```
  </Step>

  <Step title="Add to Repository">
    1. Go to repository → Settings → Deploy keys
    2. Click "Add deploy key"
    3. Title: `Auk Sync`
    4. Paste public key
    5. Check "Allow write access" if needed
    6. Click "Add key"
  </Step>

  <Step title="Configure SSH">
    Add to `~/.ssh/config`:

    ```
    Host github.com-deploy
      HostName github.com
      User git
      IdentityFile ~/.ssh/auk_deploy_key
    ```
  </Step>

  <Step title="Use in Auk">
    ```
    git@github.com-deploy:username/repository.git
    ```
  </Step>
</Steps>

### GitLab Deploy Tokens

<Steps>
  <Step title="Create Deploy Token">
    1. Go to repository → Settings → Repository → Deploy tokens
    2. Name: `Auk Sync`
    3. Scopes:
       * ✅ `read_repository`
       * ✅ `write_repository` (if needed)
    4. Click "Create deploy token"
    5. **Copy username and token**
  </Step>

  <Step title="Use in Auk">
    ```
    https://USERNAME:TOKEN@gitlab.com/username/repository.git
    ```
  </Step>
</Steps>

## OAuth (Coming Soon)

One-click authentication with popular Git services:

* **GitHub OAuth** - Authorize Auk to access your repositories
* **GitLab OAuth** - Seamless integration with GitLab
* **Automatic Token Refresh** - No manual token management

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use SSH Keys Over HTTPS">
    SSH keys are more secure and convenient:

    * No password to remember
    * Can't be accidentally committed
    * Easier to revoke if compromised
  </Accordion>

  <Accordion title="Set Token Expiration">
    Always set expiration dates for access tokens:

    * 30-90 days for active use
    * Shorter for testing
    * Rotate regularly
  </Accordion>

  <Accordion title="Use Minimal Permissions">
    Grant only necessary permissions:

    * Read-only for viewing
    * Write access only when needed
    * Avoid admin permissions
  </Accordion>

  <Accordion title="Protect Private Keys">
    Keep SSH private keys secure:

    * Never share private keys
    * Use passphrase protection
    * Store in secure location
    * Revoke if compromised
  </Accordion>

  <Accordion title="Use Deploy Keys for CI/CD">
    For automated systems:

    * Use deploy keys instead of personal keys
    * Limit to specific repositories
    * Read-only when possible
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="SSH: Permission denied (publickey)">
    **Cause:** SSH key not added or not loaded

    **Solution:**

    ```bash theme={null}
    # Check if key is loaded
    ssh-add -l

    # If not, add it
    ssh-add ~/.ssh/id_ed25519

    # Test connection
    ssh -T git@github.com
    ```
  </Accordion>

  <Accordion title="HTTPS: Authentication failed">
    **Cause:** Invalid token or expired credentials

    **Solution:**

    * Verify token is correct and not expired
    * Check token has required permissions
    * Clear credential cache and try again:

    ```bash theme={null}
    git credential-cache exit
    ```
  </Accordion>

  <Accordion title="Could not resolve hostname">
    **Cause:** Network or DNS issues

    **Solution:**

    * Check internet connection
    * Verify Git service is accessible
    * Try using IP address instead of hostname
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Git Sync Setup" href="/documentation/git-sync/setup" icon="rocket">
    Complete Git synchronization setup
  </Card>

  <Card title="Auto Sync" href="/documentation/git-sync/auto-sync" icon="arrows-rotate">
    Configure automatic synchronization
  </Card>

  <Card title="Troubleshooting" href="/documentation/git-sync/troubleshooting" icon="wrench">
    Solve common Git issues
  </Card>

  <Card title="Security" href="/support/security-policy" icon="shield">
    Learn about security best practices
  </Card>
</CardGroup>