# Service Tokens

## Deskripsi

Centralized management untuk Bearer token yang digunakan oleh microservice (GeoNetAgent, dll.).

Service Tokens adalah token sederhana berbasis SHA256 hash yang dikelola di geonet-console
sebagai single point of control, dengan sinkronisasi otomatis ke database microservice terkait.

## Tanggung Jawab

- Menerbitkan Bearer token baru untuk microservice
- Menyimpan hash token (plain text tidak pernah disimpan)
- Menyinkronkan token ke `geonetagent_dev.agent_tokens` via `AgentTokenSyncService`
- Revoke dan hapus token dengan sinkronisasi ke database microservice
- Mencatat seluruh aksi ke audit log

## Dependency

- `ServiceTokenService` — logika CRUD + audit
- `AgentTokenSyncService` — push ke `geonetagent_dev.agent_tokens`
- `AuditLogService` — audit trail
- PostgreSQL `databaselist_app` — tabel `service_tokens`
- PostgreSQL `geonetagent_dev` (10.100.1.25) — tabel `agent_tokens` (sync target)

## URL Service

`https://console.gisportal.id/api/v1/service-tokens`

## Authentication

Semua endpoint memerlukan autentikasi:
```
Authorization: Bearer <jwt_token_atau_api_token>
```

## Endpoint

| Method | Path | Deskripsi | Dokumen |
|--------|------|-----------|---------|
| GET | `/service-tokens` | List semua token | [list.md](./list.md) |
| POST | `/service-tokens` | Buat token baru | [create.md](./create.md) |
| GET | `/service-tokens/{id}` | Detail token | [show.md](./show.md) |
| POST | `/service-tokens/{id}/revoke` | Revoke token | [revoke.md](./revoke.md) |
| POST | `/service-tokens/{id}/regenerate` | Regenerate token | [regenerate.md](./regenerate.md) |
| DELETE | `/service-tokens/{id}` | Hapus permanen | [delete.md](./delete.md) |
| GET | `/service-tokens/by-service/{service}` | Filter by service | [by-service.md](./by-service.md) |
| GET | `/service-tokens/active` | Hanya token aktif | [active.md](./active.md) |
| GET | `/service-tokens/expired` | Hanya token expired | [expired.md](./expired.md) |

## Database yang Digunakan

### `service_tokens` (databaselist_app)

| Kolom | Tipe | Keterangan |
|-------|------|------------|
| `id` | UUID | Primary key |
| `name` | varchar(100) | Nama token (e.g. "GeoNetAgent-Production") |
| `service` | varchar(50) | Nama service (e.g. "GeoNetAgent") |
| `token_prefix` | varchar(20) | 16 char pertama token (display only) |
| `token_hash` | varchar(64) | SHA256 hash token lengkap |
| `is_active` | boolean | Status aktif |
| `expires_at` | timestamptz | Waktu expiry (null = tidak pernah expire) |
| `created_by` | varchar(100) | Username yang membuat |
| `created_at` | timestamptz | Waktu dibuat |
| `last_used_at` | timestamptz | Terakhir digunakan (nullable) |

### `agent_tokens` (geonetagent_dev — sync target)

| Kolom | Tipe | Keterangan |
|-------|------|------------|
| `id` | UUID | Primary key |
| `name` | varchar(100) | Nama token |
| `token_hash` | varchar(128) | SHA256 hash |
| `is_active` | boolean | Status aktif |
| `last_used_at` | timestamptz | Terakhir digunakan |
| `created_at` | timestamptz | Waktu dibuat |

## Sinkronisasi ke GeoNetAgent

Saat token dibuat, direvoke, atau dihapus di geonet-console:

```
geonet-console (ServiceTokenService)
  ↓ via AgentTokenSyncService
  ↓ DB connection: geonetagent (config/database.php)
  ↓ user: geonet_portal (INSERT, SELECT, UPDATE, DELETE)
geonetagent_dev.agent_tokens
  ↓
GeoNetAgent Collector (FastAPI) — validasi token incoming
```

**Fallback:** Jika `GEONETAGENT_DB_USERNAME` kosong di `.env`, sync di-skip dengan warning log. geonet-console tetap berjalan normal.

## Token Security

- Token plain text **hanya ditampilkan sekali** saat dibuat atau di-regenerate
- Database hanya menyimpan SHA256 hash — tidak reversible
- `token_prefix` (16 char pertama) digunakan untuk identifikasi di UI
- Jika token hilang → gunakan **Regenerate**

## Audit Log

| Event | Kondisi |
|-------|---------|
| `service_token_created` | Token baru dibuat |
| `service_token_revoked` | Token direvoke |
| `service_token_regenerated` | Token di-regenerate |
| `service_token_deleted` | Token dihapus permanen |

## Service yang Memanggil

- Admin via UI `/api-clients`
- AI Agent via API `POST /api/v1/service-tokens`

## Service yang Dipanggil

- `geonetagent_dev` PostgreSQL (sinkronisasi)
- `databaselist_audit` PostgreSQL (audit log)