layered-soul/skills/forgejo-operations/references/key-transfer.md

# SSH Key Transfer

When an SSH key was accidentally registered under the wrong Forgejo user, move it to the correct user.

## Prerequisites

- Admin API token with `write:admin` scope
- Key content (public key string)
- Old user has the key (web UI or admin access to delete)
- New user exists on Forgejo

## Steps

### 1. Delete key from old user

**Via browser (preferred):**

- Navigate to `https://<forgejo>/user/settings/keys`
- Find the key by title (full-page snapshot may be needed to see key names)
- Click Remove → confirm Yes

**Via admin API (if token has read:user scope):**

```bash
curl -s "https://<forgejo>/api/v1/user/keys" \
  -H "Authorization: token <admin-token>" | jq '.[] | {id,title}'
# Then DELETE /api/v1/user/keys/<id>
```

If browser isn't available and admin token lacks `read:user` scope, ask the operator to delete it manually.

### 2. Add key to new user via admin API

```bash
curl -s -X POST "https://<forgejo>/api/v1/admin/users/<new-username>/keys" \
  -H "Authorization: token <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"key":"<public-key>","title":"<key-title>","read_only":false}'
```

Returns key ID and user on success. 403 means admin scope missing.

### 3. Verify

```sh
ssh -T git@<forgejo>
# Expected: "Hi there, <new-username>! You've successfully authenticated..."
```

The SSH banner check confirms the transfer — not just exit code 0.

### 4. Cleanup

Delete the admin token immediately after use. Admin tokens are short-lived, single-purpose.

## Pitfalls

- "Key content has been used as non-deploy key" — key still exists on old account. Delete it first.
- Admin token can't list keys (`GET /user/keys` needs `read:user` scope). Use browser instead.
- Forgejo SSH keys are globally unique across all users. Can't add same key to two accounts.
- After transfer, the new user still needs explicit collaborator write access on each repo. SSH key ≠ repo permission.
- The verification step is the SSH banner check (`Hi there, <username>!`), not just exit code 0.

## Related

- `references/forgejo-token-scopes.md` — detailed token scope reference
- `references/git-shallow-fixes.md` — unshallowing clones, filter-branch root commits