# SSH and GPG Key Management API

Base URL: `${FORGEJO_URL}/api/v1`

## SSH Keys

### List Current User's SSH Keys

```
GET /user/keys
```

**Parameters:**
| Name | Type | In | Description |
|------|------|------|-------------|
| fingerprint | string | query | Filter by fingerprint |
| page | integer | query | Page number (1-based) |
| limit | integer | query | Page size |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/user/keys"
```

**Response:** Array of `PublicKey` objects:
| Field | Type | Description |
|-------|------|-------------|
| id | integer | Key ID |
| key | string | Public key content |
| url | string | API URL for this key |
| title | string | Key title/name |
| fingerprint | string | Key fingerprint |
| created_at | string | Creation timestamp |
| read_only | boolean | Deploy key read-only flag |

---

### Add SSH Key

```
POST /user/keys
```

**Request Body (CreateKeyOption):**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| title | string | yes | Key title/name |
| key | string | yes | Public key content |
| read_only | boolean | no | Read-only flag (for deploy keys) |

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Laptop",
    "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample... user@laptop"
  }' \
  "${FORGEJO_URL}/api/v1/user/keys"
```

---

### Get SSH Key by ID

```
GET /user/keys/{id}
```

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/user/keys/{key_id}"
```

---

### Delete SSH Key

```
DELETE /user/keys/{id}
```

```bash
curl -s -X DELETE \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/user/keys/{key_id}"
```

Returns `204 No Content` on success.

---

### List User's Public SSH Keys

```
GET /users/{username}/keys
```

**Parameters:**
| Name | Type | In | Description |
|------|------|------|-------------|
| fingerprint | string | query | Filter by fingerprint |
| page | integer | query | Page number (1-based) |
| limit | integer | query | Page size |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/users/{username}/keys"
```

---

## GPG Keys

### List Current User's GPG Keys

```
GET /user/gpg_keys
```

**Parameters:**
| Name | Type | In | Description |
|------|------|------|-------------|
| page | integer | query | Page number (1-based) |
| limit | integer | query | Page size |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/user/gpg_keys"
```

**Response:** Array of `GPGKey` objects:
| Field | Type | Description |
|-------|------|-------------|
| id | integer | Key ID |
| primary_key_id | string | Primary key ID |
| key_id | string | GPG key ID |
| public_key | string | Armored public key |
| emails | array | Associated email objects |
| subkeys | array | Subkey objects |
| can_sign | boolean | Key can sign |
| can_encrypt_comms | boolean | Can encrypt communications |
| can_encrypt_storage | boolean | Can encrypt storage |
| can_certify | boolean | Can certify |
| verified | boolean | Key is verified |
| created_at | string | Creation timestamp |
| expires_at | string | Expiration timestamp |

---

### Add GPG Key

```
POST /user/gpg_keys
```

**Request Body (CreateGPGKeyOption):**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| armored_public_key | string | yes | ASCII-armored GPG public key |
| armored_signature | string | no | Signature for verification |

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "armored_public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...\n-----END PGP PUBLIC KEY BLOCK-----"
  }' \
  "${FORGEJO_URL}/api/v1/user/gpg_keys"
```

---

### Get GPG Key by ID

```
GET /user/gpg_keys/{id}
```

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/user/gpg_keys/{key_id}"
```

---

### Delete GPG Key

```
DELETE /user/gpg_keys/{id}
```

```bash
curl -s -X DELETE \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/user/gpg_keys/{key_id}"
```

Returns `204 No Content` on success.

---

### List User's GPG Keys

```
GET /users/{username}/gpg_keys
```

**Parameters:**
| Name | Type | In | Description |
|------|------|------|-------------|
| page | integer | query | Page number (1-based) |
| limit | integer | query | Page size |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/users/{username}/gpg_keys"
```

---

## GPG Key Verification

### Get Token for GPG Key Verification

```
GET /user/gpg_key_token
```

Returns a token that must be signed with the GPG key to verify ownership.

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/user/gpg_key_token"
```

**Response:** Plain text token string.

---

### Verify GPG Key

```
POST /user/gpg_key_verify
```

Submit a signed token to verify GPG key ownership.

```bash
# 1. Get the token
TOKEN=$(curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/user/gpg_key_token")

# 2. Sign the token with your GPG key
SIGNATURE=$(echo -n "$TOKEN" | gpg --armor --detach-sign)

# 3. Submit the verification
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d "{\"key_id\": \"ABCDEF1234567890\", \"signature\": \"$SIGNATURE\"}" \
  "${FORGEJO_URL}/api/v1/user/gpg_key_verify"
```

---

## Instance Signing Keys

### Instance Signing GPG Key

```
GET /signing-key.gpg
```

Returns the instance-level GPG signing key (used for commit signing).

```bash
curl -s "${FORGEJO_URL}/api/v1/signing-key.gpg"
```

---

### Instance Signing SSH Key

```
GET /signing-key.ssh
```

Returns the instance-level SSH signing key.

```bash
curl -s "${FORGEJO_URL}/api/v1/signing-key.ssh"
```

---

### Repository Signing GPG Key

```
GET /repos/{owner}/{repo}/signing-key.gpg
```

Returns the repository-specific GPG signing key (if different from instance key).

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/signing-key.gpg"
```
