feat(api): implement API key management and authentication enhancements

- Added endpoints for managing API keys, including creation, retrieval, updating, and revocation.
- Introduced a new Auth session endpoint to retrieve current tenant and role information.
- Updated the authentication middleware to support API key-based authentication and track last used timestamps.
- Enhanced documentation to reflect new API key functionalities and usage guidelines.
- Improved logging for demo authentication scenarios.

internal/authkey/token.go

@@ -0,0 +1,34 @@
+// Package authkey generates API tokens and derives lookup hashes (no persistence).
+package authkey
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"fmt"
+)
+
+const tokenPrefix = "evobgp_"
+
+// GenerateToken returns a new bearer token (evobgp_ + 32 random bytes, base64url).
+func GenerateToken() (string, error) {
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		return "", fmt.Errorf("authkey: generate token: %w", err)
+	}
+	return tokenPrefix + base64.RawURLEncoding.EncodeToString(b), nil
+}
+
+// HashToken returns SHA-256 of the full token (32 bytes).
+func HashToken(token string) []byte {
+	sum := sha256.Sum256([]byte(token))
+	return sum[:]
+}
+
+// Prefix returns the first 8 characters of the token for display.
+func Prefix(token string) string {
+	if len(token) <= 8 {
+		return token
+	}
+	return token[:8]
+}

internal/httpapi/api_key_resolver.go

@@ -0,0 +1,66 @@
+package httpapi
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"sync"
+
+	"evobgp/internal/store"
+)
+
+type apiKeyResolver struct {
+	mu sync.RWMutex
+
+	envByToken map[string]apiKeyRecord
+	byHash     map[string]apiKeyRecord
+}
+
+func newAPIKeyResolver(envSpec string, st store.Backend) (*apiKeyResolver, error) {
+	r := &apiKeyResolver{
+		envByToken: make(map[string]apiKeyRecord),
+		byHash:     make(map[string]apiKeyRecord),
+	}
+	for _, rec := range parseAPIKeysSpec(envSpec) {
+		r.envByToken[rec.token] = rec
+	}
+	return r, r.reloadFromStore(st)
+}
+
+func (r *apiKeyResolver) reloadFromStore(st store.Backend) error {
+	rows, err := st.ListActiveAPIKeyHashes()
+	if err != nil {
+		return err
+	}
+	byHash := make(map[string]apiKeyRecord, len(rows))
+	for _, row := range rows {
+		if len(row.TokenHash) != 32 {
+			continue
+		}
+		byHash[hex.EncodeToString(row.TokenHash)] = apiKeyRecord{
+			token:    "",
+			tenantID: row.TenantID,
+			role:     row.Role,
+			keyID:    row.ID,
+		}
+	}
+	r.mu.Lock()
+	r.byHash = byHash
+	r.mu.Unlock()
+	return nil
+}
+
+func (r *apiKeyResolver) Reload(st store.Backend) error {
+	return r.reloadFromStore(st)
+}
+
+func (r *apiKeyResolver) Lookup(raw string) (apiKeyRecord, bool) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	if rec, ok := r.envByToken[raw]; ok {
+		return rec, true
+	}
+	sum := sha256.Sum256([]byte(raw))
+	key := hex.EncodeToString(sum[:])
+	rec, ok := r.byHash[key]
+	return rec, ok
+}

internal/httpapi/auth.go

@@ -15,6 +15,7 @@ type Auth struct {
 	TenantID string
 	Role     string // viewer, editor, operator, node
 	Token    string
+	APIKeyID string // non-empty for DB-managed keys
 }
 
 func authFromContext(ctx context.Context) (Auth, bool) {
@@ -26,6 +27,7 @@ type apiKeyRecord struct {
 	token    string
 	tenantID string
 	role     string
+	keyID    string // set for DB-managed keys (last_used_at)
 }
 
 func parseAPIKeysSpec(spec string) []apiKeyRecord {
@@ -54,20 +56,6 @@ func parseAPIKeysSpec(spec string) []apiKeyRecord {
 
 func (s *Server) authMiddleware(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if s.insecureDev {
-			h := r.Header.Get("Authorization")
-			const p = "Bearer "
-			if strings.HasPrefix(h, p) {
-				tok := strings.TrimSpace(strings.TrimPrefix(h, p))
-				if tok == "dev" {
-					if a, ok := s.devAuth(); ok {
-						r = r.WithContext(context.WithValue(r.Context(), authCtxKey, a))
-						next.ServeHTTP(w, r)
-						return
-					}
-				}
-			}
-		}
 		h := r.Header.Get("Authorization")
 		const p = "Bearer "
 		if !strings.HasPrefix(h, p) {
@@ -75,18 +63,22 @@ func (s *Server) authMiddleware(next http.Handler) http.Handler {
 			return
 		}
 		raw := strings.TrimSpace(strings.TrimPrefix(h, p))
-		var matched *apiKeyRecord
-		for i := range s.apiKeys {
-			if s.apiKeys[i].token == raw {
-				matched = &s.apiKeys[i]
-				break
+		if raw == "dev" {
+			if a, ok := s.devAuth(); ok {
+				r = r.WithContext(context.WithValue(r.Context(), authCtxKey, a))
+				next.ServeHTTP(w, r)
+				return
 			}
 		}
-		if matched == nil {
+		matched, ok := s.keyResolver.Lookup(raw)
+		if !ok {
 			writeProblem(w, http.StatusUnauthorized, "Unauthorized", "unknown api key")
 			return
 		}
-		a := Auth{TenantID: matched.tenantID, Role: matched.role, Token: raw}
+		a := Auth{TenantID: matched.tenantID, Role: matched.role, Token: raw, APIKeyID: matched.keyID}
+		if matched.keyID != "" {
+			go func(id string) { _ = s.store.TouchAPIKeyLastUsed(id) }(matched.keyID)
+		}
 		r = r.WithContext(context.WithValue(r.Context(), authCtxKey, a))
 		next.ServeHTTP(w, r)
 	})

internal/httpapi/routes_api_keys.go

@@ -0,0 +1,217 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+	"time"
+
+	"evobgp/internal/store"
+)
+
+func (s *Server) registerAPIKeyRoutes(m *http.ServeMux) {
+	m.HandleFunc("GET /auth/session", s.handleAuthSession)
+	m.HandleFunc("GET /api-keys", s.handleListAPIKeys)
+	m.HandleFunc("POST /api-keys", s.handlePostAPIKey)
+	m.HandleFunc("GET /api-keys/{id}", s.handleGetAPIKey)
+	m.HandleFunc("PATCH /api-keys/{id}", s.handlePatchAPIKey)
+	m.HandleFunc("DELETE /api-keys/{id}", s.handleDeleteAPIKey)
+	m.HandleFunc("POST /api-keys/{id}/rotate", s.handleRotateAPIKey)
+}
+
+func (s *Server) handleAuthSession(w http.ResponseWriter, r *http.Request) {
+	a, ok := authFromContext(r.Context())
+	if !ok || !s.requireAtLeast(w, a, "viewer") {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"tenant_id": a.TenantID,
+		"role":      a.Role,
+	})
+}
+
+func apiKeyJSON(k *store.APIKey) map[string]any {
+	m := map[string]any{
+		"id":         k.ID,
+		"name":       k.Name,
+		"role":       k.Role,
+		"prefix":     k.Prefix,
+		"created_at": k.CreatedAt.UTC().Format(time.RFC3339),
+		"updated_at": k.UpdatedAt.UTC().Format(time.RFC3339),
+	}
+	if k.ExpiresAt != nil {
+		m["expires_at"] = k.ExpiresAt.UTC().Format(time.RFC3339)
+	} else {
+		m["expires_at"] = nil
+	}
+	if k.RevokedAt != nil {
+		m["revoked_at"] = k.RevokedAt.UTC().Format(time.RFC3339)
+	} else {
+		m["revoked_at"] = nil
+	}
+	if k.LastUsedAt != nil {
+		m["last_used_at"] = k.LastUsedAt.UTC().Format(time.RFC3339)
+	} else {
+		m["last_used_at"] = nil
+	}
+	return m
+}
+
+func (s *Server) handleListAPIKeys(w http.ResponseWriter, r *http.Request) {
+	a, ok := authFromContext(r.Context())
+	if !ok || !s.requireAtLeast(w, a, "operator") {
+		return
+	}
+	list, err := s.store.ListAPIKeys(a.TenantID)
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	writePaginatedListJSON(w, r, list, func(k *store.APIKey) map[string]any {
+		return apiKeyJSON(k)
+	})
+}
+
+func (s *Server) handleGetAPIKey(w http.ResponseWriter, r *http.Request) {
+	a, ok := authFromContext(r.Context())
+	if !ok || !s.requireAtLeast(w, a, "operator") {
+		return
+	}
+	k, err := s.store.GetAPIKey(a.TenantID, r.PathValue("id"))
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, apiKeyJSON(k))
+}
+
+func (s *Server) handlePostAPIKey(w http.ResponseWriter, r *http.Request) {
+	a, ok := authFromContext(r.Context())
+	if !ok || !s.requireAtLeast(w, a, "operator") {
+		return
+	}
+	var body struct {
+		Name      string  `json:"name"`
+		Role      string  `json:"role"`
+		ExpiresAt *string `json:"expires_at"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeProblem(w, http.StatusBadRequest, "Bad Request", "invalid json")
+		return
+	}
+	in := &store.APIKeyCreate{
+		Name: strings.TrimSpace(body.Name),
+		Role: strings.TrimSpace(body.Role),
+	}
+	if body.ExpiresAt != nil && strings.TrimSpace(*body.ExpiresAt) != "" {
+		t, err := time.Parse(time.RFC3339, strings.TrimSpace(*body.ExpiresAt))
+		if err != nil {
+			writeProblem(w, http.StatusUnprocessableEntity, "Unprocessable Entity", "invalid expires_at")
+			return
+		}
+		in.ExpiresAt = &t
+	}
+	created, err := s.store.CreateAPIKey(a.TenantID, in)
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	if err := s.keyResolver.Reload(s.store); err != nil {
+		writeProblem(w, http.StatusInternalServerError, "Internal Server Error", "failed to reload api keys")
+		return
+	}
+	out := apiKeyJSON(&created.APIKey)
+	out["token"] = created.Token
+	writeJSON(w, http.StatusCreated, out)
+}
+
+func (s *Server) handlePatchAPIKey(w http.ResponseWriter, r *http.Request) {
+	a, ok := authFromContext(r.Context())
+	if !ok || !s.requireAtLeast(w, a, "operator") {
+		return
+	}
+	var raw map[string]json.RawMessage
+	if err := json.NewDecoder(r.Body).Decode(&raw); err != nil {
+		writeProblem(w, http.StatusBadRequest, "Bad Request", "invalid json")
+		return
+	}
+	patch := &store.APIKeyPatch{}
+	if v, ok := raw["name"]; ok {
+		var name string
+		if err := json.Unmarshal(v, &name); err != nil {
+			writeProblem(w, http.StatusBadRequest, "Bad Request", "invalid name")
+			return
+		}
+		patch.Name = &name
+	}
+	if v, ok := raw["role"]; ok {
+		var role string
+		if err := json.Unmarshal(v, &role); err != nil {
+			writeProblem(w, http.StatusBadRequest, "Bad Request", "invalid role")
+			return
+		}
+		patch.Role = &role
+	}
+	if v, ok := raw["expires_at"]; ok {
+		if string(v) == "null" {
+			patch.ClearExpiresAt = true
+		} else {
+			var s string
+			if err := json.Unmarshal(v, &s); err != nil {
+				writeProblem(w, http.StatusBadRequest, "Bad Request", "invalid expires_at")
+				return
+			}
+			t, err := time.Parse(time.RFC3339, strings.TrimSpace(s))
+			if err != nil {
+				writeProblem(w, http.StatusUnprocessableEntity, "Unprocessable Entity", "invalid expires_at")
+				return
+			}
+			patch.ExpiresAt = &t
+		}
+	}
+	k, err := s.store.UpdateAPIKey(a.TenantID, r.PathValue("id"), patch)
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	if err := s.keyResolver.Reload(s.store); err != nil {
+		writeProblem(w, http.StatusInternalServerError, "Internal Server Error", "failed to reload api keys")
+		return
+	}
+	writeJSON(w, http.StatusOK, apiKeyJSON(k))
+}
+
+func (s *Server) handleDeleteAPIKey(w http.ResponseWriter, r *http.Request) {
+	a, ok := authFromContext(r.Context())
+	if !ok || !s.requireAtLeast(w, a, "operator") {
+		return
+	}
+	if err := s.store.RevokeAPIKey(a.TenantID, r.PathValue("id")); err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	if err := s.keyResolver.Reload(s.store); err != nil {
+		writeProblem(w, http.StatusInternalServerError, "Internal Server Error", "failed to reload api keys")
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func (s *Server) handleRotateAPIKey(w http.ResponseWriter, r *http.Request) {
+	a, ok := authFromContext(r.Context())
+	if !ok || !s.requireAtLeast(w, a, "operator") {
+		return
+	}
+	rotated, err := s.store.RotateAPIKey(a.TenantID, r.PathValue("id"))
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	if err := s.keyResolver.Reload(s.store); err != nil {
+		writeProblem(w, http.StatusInternalServerError, "Internal Server Error", "failed to reload api keys")
+		return
+	}
+	out := apiKeyJSON(&rotated.APIKey)
+	out["token"] = rotated.Token
+	writeJSON(w, http.StatusOK, out)
+}

internal/httpapi/routes_api_keys_test.go

@@ -0,0 +1,119 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestBearerDevWithoutInsecureDev(t *testing.T) {
+	srv, err := New(Options{SeedDemo: true, BundleSeedHex: testBundleSeed})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer srv.Close()
+
+	ts := httptest.NewServer(srv.Handler())
+	defer ts.Close()
+
+	req, _ := http.NewRequest(http.MethodGet, ts.URL+"/v1/modules?limit=1", nil)
+	req.Header.Set("Authorization", "Bearer dev")
+	resp, err := ts.Client().Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		b, _ := io.ReadAll(resp.Body)
+		t.Fatalf("status=%d body=%s", resp.StatusCode, b)
+	}
+}
+
+func TestAPIKeysCRUDAndAuth(t *testing.T) {
+	srv, err := New(Options{SeedDemo: true, BundleSeedHex: testBundleSeed})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer srv.Close()
+	tenant, _, _, _, _ := srv.Store().DemoIDs()
+	mustSetTestAPIKeys(t, srv, "opkey|"+tenant+"|operator")
+
+	ts := httptest.NewServer(srv.Handler())
+	defer ts.Close()
+	client := ts.Client()
+	base := ts.URL
+
+	reqCreate, _ := http.NewRequest(http.MethodPost, base+"/v1/api-keys", strings.NewReader(`{"name":"ci","role":"editor"}`))
+	reqCreate.Header.Set("Authorization", "Bearer opkey")
+	reqCreate.Header.Set("Content-Type", "application/json")
+	respCreate, err := client.Do(reqCreate)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer respCreate.Body.Close()
+	if respCreate.StatusCode != http.StatusCreated {
+		b, _ := io.ReadAll(respCreate.Body)
+		t.Fatalf("create status=%d body=%s", respCreate.StatusCode, b)
+	}
+	var created map[string]any
+	if err := json.NewDecoder(respCreate.Body).Decode(&created); err != nil {
+		t.Fatal(err)
+	}
+	token, _ := created["token"].(string)
+	if token == "" {
+		t.Fatal("missing token in create response")
+	}
+	id, _ := created["id"].(string)
+	if id == "" {
+		t.Fatal("missing id")
+	}
+
+	reqMod, _ := http.NewRequest(http.MethodGet, base+"/v1/modules?limit=1", nil)
+	reqMod.Header.Set("Authorization", "Bearer "+token)
+	respMod, err := client.Do(reqMod)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer respMod.Body.Close()
+	if respMod.StatusCode != http.StatusOK {
+		b, _ := io.ReadAll(respMod.Body)
+		t.Fatalf("modules status=%d body=%s", respMod.StatusCode, b)
+	}
+
+	reqDel, _ := http.NewRequest(http.MethodDelete, base+"/v1/api-keys/"+id, nil)
+	reqDel.Header.Set("Authorization", "Bearer opkey")
+	respDel, err := client.Do(reqDel)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer respDel.Body.Close()
+	if respDel.StatusCode != http.StatusNoContent {
+		t.Fatalf("delete status=%d", respDel.StatusCode)
+	}
+
+	reqAfter, _ := http.NewRequest(http.MethodGet, base+"/v1/modules?limit=1", nil)
+	reqAfter.Header.Set("Authorization", "Bearer "+token)
+	respAfter, err := client.Do(reqAfter)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer respAfter.Body.Close()
+	if respAfter.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("expected 401 after revoke, got %d", respAfter.StatusCode)
+	}
+
+	mustSetTestAPIKeys(t, srv, "nodekey|"+tenant+"|node,opkey|"+tenant+"|operator")
+	reqNode2, _ := http.NewRequest(http.MethodGet, base+"/v1/api-keys", nil)
+	reqNode2.Header.Set("Authorization", "Bearer nodekey")
+	respNode, err := client.Do(reqNode2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer respNode.Body.Close()
+	if respNode.StatusCode != http.StatusForbidden {
+		t.Fatalf("node list api-keys status=%d want 403", respNode.StatusCode)
+	}
+}

internal/httpapi/routes_crud.go

@@ -70,6 +70,8 @@ func (s *Server) registerCRUDRoutes(m *http.ServeMux) {
 
 	m.HandleFunc("GET /settings", s.handleGetSettings)
 	m.HandleFunc("PATCH /settings", s.handlePatchSettings)
+
+	s.registerAPIKeyRoutes(m)
 }
 
 func (s *Server) handlePostModule(w http.ResponseWriter, r *http.Request) {

internal/httpapi/routes_crud_csv_test.go

@@ -21,7 +21,7 @@ func TestModuleEntriesCSVImportExportIPRanges(t *testing.T) {
 	defer srv.Close()
 
 	tenant, _, modIP, _, _ := srv.Store().DemoIDs()
-	srv.apiKeys = parseAPIKeysSpec("opkey|" + tenant + "|operator")
+	mustSetTestAPIKeys(t, srv, "opkey|"+tenant+"|operator")
 
 	ts := httptest.NewServer(srv.Handler())
 	defer ts.Close()

internal/httpapi/routes_crud_list_test.go

@@ -17,7 +17,7 @@ func TestNestedModuleListPagination(t *testing.T) {
 	}
 	defer srv.Close()
 	tenant, _, modIP, _, _ := srv.Store().DemoIDs()
-	srv.apiKeys = parseAPIKeysSpec("edkey|" + tenant + "|editor")
+	mustSetTestAPIKeys(t, srv, "edkey|"+tenant+"|editor")
 
 	ts := httptest.NewServer(srv.Handler())
 	defer ts.Close()

internal/httpapi/server.go

@@ -21,8 +21,7 @@ type Server struct {
 	pgPool      *pgxpool.Pool
 	jobs        *jobs.Registry
 	bundlePriv  ed25519.PrivateKey
-	apiKeys     []apiKeyRecord
-	insecureDev bool
+	keyResolver *apiKeyResolver
 	corsOrigins []string
 	cdnHTTP     *http.Client
 	mux         *http.ServeMux
@@ -60,13 +59,16 @@ func New(opts Options) (*Server, error) {
 		_, priv, _ = ed25519.GenerateKey(rand.Reader)
 	}
 
+	resolver, err := newAPIKeyResolver(opts.APIKeys, backend)
+	if err != nil {
+		return nil, err
+	}
 	s := &Server{
 		store:       backend,
 		pgPool:      pool,
 		jobs:        reg,
 		bundlePriv:  priv,
-		apiKeys:     parseAPIKeysSpec(opts.APIKeys),
-		insecureDev: opts.InsecureDev && opts.SeedDemo,
+		keyResolver: resolver,
 		corsOrigins: parseCORSOrigins(opts.CORSAllowedOrigins),
 		cdnHTTP:     NewCDNHTTPClient(),
 	}

internal/httpapi/server_test.go

@@ -29,7 +29,7 @@ func TestAPIRefreshApplyJobsBundle(t *testing.T) {
 	}
 	defer srv.Close()
 	tenant, modCDN, modIP, rev, speaker := srv.Store().DemoIDs()
-	srv.apiKeys = parseAPIKeysSpec("nodekey|" + tenant + "|node,opkey|" + tenant + "|operator,edkey|" + tenant + "|editor")
+	mustSetTestAPIKeys(t, srv, "nodekey|"+tenant+"|node,opkey|"+tenant+"|operator,edkey|"+tenant+"|editor")
 
 	ts := httptest.NewServer(srv.Handler())
 	defer ts.Close()

internal/httpapi/test_helpers.go

@@ -0,0 +1,12 @@
+package httpapi
+
+import "testing"
+
+func mustSetTestAPIKeys(t *testing.T, srv *Server, spec string) {
+	t.Helper()
+	resolver, err := newAPIKeyResolver(spec, srv.store)
+	if err != nil {
+		t.Fatal(err)
+	}
+	srv.keyResolver = resolver
+}

internal/repository/postgres_api_key.go

@@ -0,0 +1,203 @@
+package repository
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"evobgp/internal/authkey"
+	"evobgp/internal/store"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+)
+
+func (p *Postgres) ListAPIKeys(tenantID string) ([]*store.APIKey, error) {
+	ctx := context.Background()
+	rows, err := p.pool.Query(ctx, `
+		SELECT id::text, name, role, token_prefix, created_at, updated_at, expires_at, revoked_at, last_used_at
+		FROM api_key WHERE tenant_id=$1 ORDER BY created_at DESC`, tenantID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []*store.APIKey
+	for rows.Next() {
+		k, err := scanAPIKeyRow(rows.Scan, tenantID)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, k)
+	}
+	return out, rows.Err()
+}
+
+func (p *Postgres) GetAPIKey(tenantID, id string) (*store.APIKey, error) {
+	ctx := context.Background()
+	row := p.pool.QueryRow(ctx, `
+		SELECT id::text, name, role, token_prefix, created_at, updated_at, expires_at, revoked_at, last_used_at
+		FROM api_key WHERE id=$1 AND tenant_id=$2`, id, tenantID)
+	k, err := scanAPIKeyRow(row.Scan, tenantID)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, store.ErrNotFound
+		}
+		return nil, err
+	}
+	return k, nil
+}
+
+func (p *Postgres) CreateAPIKey(tenantID string, in *store.APIKeyCreate) (*store.APIKeyWithSecret, error) {
+	if in == nil || strings.TrimSpace(in.Name) == "" || !store.ValidAPIKeyRole(in.Role) {
+		return nil, store.ErrInvalidInput
+	}
+	tok, err := authkey.GenerateToken()
+	if err != nil {
+		return nil, err
+	}
+	id := uuid.NewString()
+	hash := authkey.HashToken(tok)
+	prefix := authkey.Prefix(tok)
+	role := strings.ToLower(strings.TrimSpace(in.Role))
+	ctx := context.Background()
+	_, err = p.pool.Exec(ctx, `
+		INSERT INTO api_key (id, tenant_id, name, role, token_prefix, token_hash, expires_at)
+		VALUES ($1,$2,$3,$4,$5,$6,$7)`,
+		id, tenantID, strings.TrimSpace(in.Name), role, prefix, hash, in.ExpiresAt)
+	if err != nil {
+		return nil, err
+	}
+	k, err := p.GetAPIKey(tenantID, id)
+	if err != nil {
+		return nil, err
+	}
+	return &store.APIKeyWithSecret{APIKey: *k, Token: tok}, nil
+}
+
+func (p *Postgres) UpdateAPIKey(tenantID, id string, patch *store.APIKeyPatch) (*store.APIKey, error) {
+	cur, err := p.GetAPIKey(tenantID, id)
+	if err != nil {
+		return nil, err
+	}
+	if cur.RevokedAt != nil {
+		return nil, store.ErrInvalidInput
+	}
+	if patch == nil {
+		return nil, store.ErrInvalidInput
+	}
+	if patch.Name != nil {
+		n := strings.TrimSpace(*patch.Name)
+		if n == "" {
+			return nil, store.ErrInvalidInput
+		}
+		cur.Name = n
+	}
+	if patch.Role != nil {
+		if !store.ValidAPIKeyRole(*patch.Role) {
+			return nil, store.ErrInvalidInput
+		}
+		cur.Role = strings.ToLower(strings.TrimSpace(*patch.Role))
+	}
+	if patch.ClearExpiresAt {
+		cur.ExpiresAt = nil
+	} else if patch.ExpiresAt != nil {
+		cur.ExpiresAt = patch.ExpiresAt
+	}
+	ctx := context.Background()
+	_, err = p.pool.Exec(ctx, `
+		UPDATE api_key SET name=$3, role=$4, expires_at=$5, updated_at=now()
+		WHERE id=$1 AND tenant_id=$2 AND revoked_at IS NULL`,
+		id, tenantID, cur.Name, cur.Role, cur.ExpiresAt)
+	if err != nil {
+		return nil, err
+	}
+	return p.GetAPIKey(tenantID, id)
+}
+
+func (p *Postgres) RevokeAPIKey(tenantID, id string) error {
+	ctx := context.Background()
+	tag, err := p.pool.Exec(ctx, `
+		UPDATE api_key SET revoked_at=now(), updated_at=now()
+		WHERE id=$1 AND tenant_id=$2 AND revoked_at IS NULL`, id, tenantID)
+	if err != nil {
+		return err
+	}
+	if tag.RowsAffected() == 0 {
+		return store.ErrNotFound
+	}
+	return nil
+}
+
+func (p *Postgres) RotateAPIKey(tenantID, id string) (*store.APIKeyWithSecret, error) {
+	cur, err := p.GetAPIKey(tenantID, id)
+	if err != nil {
+		return nil, err
+	}
+	if cur.RevokedAt != nil {
+		return nil, store.ErrInvalidInput
+	}
+	tok, err := authkey.GenerateToken()
+	if err != nil {
+		return nil, err
+	}
+	hash := authkey.HashToken(tok)
+	prefix := authkey.Prefix(tok)
+	ctx := context.Background()
+	_, err = p.pool.Exec(ctx, `
+		UPDATE api_key SET token_hash=$3, token_prefix=$4, updated_at=now()
+		WHERE id=$1 AND tenant_id=$2 AND revoked_at IS NULL`,
+		id, tenantID, hash, prefix)
+	if err != nil {
+		return nil, err
+	}
+	k, err := p.GetAPIKey(tenantID, id)
+	if err != nil {
+		return nil, err
+	}
+	return &store.APIKeyWithSecret{APIKey: *k, Token: tok}, nil
+}
+
+func (p *Postgres) ListActiveAPIKeyHashes() ([]store.APIKeyAuthRow, error) {
+	ctx := context.Background()
+	rows, err := p.pool.Query(ctx, `
+		SELECT id::text, tenant_id::text, role, token_hash
+		FROM api_key
+		WHERE revoked_at IS NULL AND (expires_at IS NULL OR expires_at > now())`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []store.APIKeyAuthRow
+	for rows.Next() {
+		var row store.APIKeyAuthRow
+		var hash []byte
+		if err := rows.Scan(&row.ID, &row.TenantID, &row.Role, &hash); err != nil {
+			return nil, err
+		}
+		row.TokenHash = append([]byte(nil), hash...)
+		out = append(out, row)
+	}
+	return out, rows.Err()
+}
+
+func (p *Postgres) TouchAPIKeyLastUsed(id string) error {
+	ctx := context.Background()
+	_, err := p.pool.Exec(ctx, `UPDATE api_key SET last_used_at=now() WHERE id=$1`, id)
+	return err
+}
+
+type scanFn func(dest ...any) error
+
+func scanAPIKeyRow(scan scanFn, tenantID string) (*store.APIKey, error) {
+	var k store.APIKey
+	k.TenantID = tenantID
+	var expires, revoked, lastUsed *time.Time
+	if err := scan(&k.ID, &k.Name, &k.Role, &k.Prefix, &k.CreatedAt, &k.UpdatedAt, &expires, &revoked, &lastUsed); err != nil {
+		return nil, err
+	}
+	k.ExpiresAt = expires
+	k.RevokedAt = revoked
+	k.LastUsedAt = lastUsed
+	return &k, nil
+}

internal/store/backend.go

@@ -2,6 +2,7 @@ package store
 
 import (
 	"context"
+	"strings"
 	"time"
 )
 
@@ -88,6 +89,15 @@ type Backend interface {
 	ListGlobalSettings(tenantID string) (map[string]any, error)
 	PatchGlobalSettings(tenantID string, patch map[string]any) error
 
+	ListAPIKeys(tenantID string) ([]*APIKey, error)
+	GetAPIKey(tenantID, id string) (*APIKey, error)
+	CreateAPIKey(tenantID string, in *APIKeyCreate) (*APIKeyWithSecret, error)
+	UpdateAPIKey(tenantID, id string, patch *APIKeyPatch) (*APIKey, error)
+	RevokeAPIKey(tenantID, id string) error
+	RotateAPIKey(tenantID, id string) (*APIKeyWithSecret, error)
+	ListActiveAPIKeyHashes() ([]APIKeyAuthRow, error)
+	TouchAPIKeyLastUsed(id string) error
+
 	// Module prefix snapshots cache last successful collect per module (pipeline ingest/render).
 	GetModulePrefixSnapshot(tenantID, moduleID string) (*ModulePrefixSnapshot, bool, error)
 	SetModulePrefixSnapshot(tenantID, moduleID, inputHash string, prefixes []PrefixRow) error
@@ -227,6 +237,59 @@ type CommunityPatch struct {
 	ValueJSON *string `json:"value_json,omitempty"`
 }
 
+// APIKey is tenant-scoped API key metadata (secret never stored in plaintext).
+type APIKey struct {
+	ID         string     `json:"id"`
+	TenantID   string     `json:"tenant_id,omitempty"`
+	Name       string     `json:"name"`
+	Role       string     `json:"role"`
+	Prefix     string     `json:"prefix"`
+	CreatedAt  time.Time  `json:"created_at"`
+	UpdatedAt  time.Time  `json:"updated_at"`
+	ExpiresAt  *time.Time `json:"expires_at,omitempty"`
+	RevokedAt  *time.Time `json:"revoked_at,omitempty"`
+	LastUsedAt *time.Time `json:"last_used_at,omitempty"`
+}
+
+// APIKeyCreate is input for issuing a new key.
+type APIKeyCreate struct {
+	Name      string     `json:"name"`
+	Role      string     `json:"role"`
+	ExpiresAt *time.Time `json:"expires_at,omitempty"`
+}
+
+// APIKeyPatch is a partial update (role change affects auth after resolver reload).
+type APIKeyPatch struct {
+	Name             *string    `json:"name,omitempty"`
+	Role             *string    `json:"role,omitempty"`
+	ExpiresAt        *time.Time `json:"expires_at,omitempty"`
+	ClearExpiresAt   bool       `json:"-"`
+}
+
+// APIKeyWithSecret is returned only on create/rotate.
+type APIKeyWithSecret struct {
+	APIKey
+	Token string `json:"token"`
+}
+
+// APIKeyAuthRow is used to build the in-process auth index.
+type APIKeyAuthRow struct {
+	ID        string
+	TenantID  string
+	Role      string
+	TokenHash []byte
+}
+
+// ValidAPIKeyRole reports whether role is allowed for API keys.
+func ValidAPIKeyRole(role string) bool {
+	switch strings.ToLower(strings.TrimSpace(role)) {
+	case "viewer", "editor", "operator", "node":
+		return true
+	default:
+		return false
+	}
+}
+
 type PeerPatch struct {
 	Neighbor     *string `json:"neighbor,omitempty"`
 	RemoteASN    *int64  `json:"remote_asn,omitempty"`

internal/store/memory.go

@@ -43,6 +43,7 @@ type Memory struct {
 	revPrefixes     map[string][]PrefixRow
 	moduleSnapshots map[string]*moduleSnapshotRec
 	asnPrefixCache  map[int64]*ASNPrefixCacheEntry
+	apiKeys         map[string]*apiKeyRec
 
 	// DemoIDs valid after SeedDemo()
 	demoTenantID   string
@@ -57,6 +58,11 @@ type publishedInfo struct {
 	PublishedAt time.Time
 }
 
+type apiKeyRec struct {
+	APIKey
+	TokenHash []byte
+}
+
 type Tenant struct {
 	ID   string
 	Name string
@@ -133,6 +139,7 @@ func NewMemory() *Memory {
 		revPrefixes:       make(map[string][]PrefixRow),
 		moduleSnapshots:   make(map[string]*moduleSnapshotRec),
 		asnPrefixCache:    make(map[int64]*ASNPrefixCacheEntry),
+		apiKeys:           make(map[string]*apiKeyRec),
 	}
 }
 

internal/store/memory_api_key.go

@@ -0,0 +1,184 @@
+package store
+
+import (
+	"strings"
+	"time"
+
+	"evobgp/internal/authkey"
+
+	"github.com/google/uuid"
+)
+
+func (m *Memory) ListAPIKeys(tenantID string) ([]*APIKey, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	var out []*APIKey
+	for _, rec := range m.apiKeys {
+		if rec.TenantID == tenantID {
+			out = append(out, apiKeyCopy(&rec.APIKey))
+		}
+	}
+	return out, nil
+}
+
+func (m *Memory) GetAPIKey(tenantID, id string) (*APIKey, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	rec, ok := m.apiKeys[id]
+	if !ok || rec.TenantID != tenantID {
+		return nil, ErrNotFound
+	}
+	return apiKeyCopy(&rec.APIKey), nil
+}
+
+func (m *Memory) CreateAPIKey(tenantID string, in *APIKeyCreate) (*APIKeyWithSecret, error) {
+	if in == nil || strings.TrimSpace(in.Name) == "" || !ValidAPIKeyRole(in.Role) {
+		return nil, ErrInvalidInput
+	}
+	tok, err := authkey.GenerateToken()
+	if err != nil {
+		return nil, err
+	}
+	now := time.Now().UTC()
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if _, ok := m.tenants[tenantID]; !ok {
+		return nil, ErrTenantScope
+	}
+	id := uuid.NewString()
+	k := &apiKeyRec{
+		APIKey: APIKey{
+			ID:        id,
+			TenantID:  tenantID,
+			Name:      strings.TrimSpace(in.Name),
+			Role:      strings.ToLower(strings.TrimSpace(in.Role)),
+			Prefix:    authkey.Prefix(tok),
+			CreatedAt: now,
+			UpdatedAt: now,
+			ExpiresAt: in.ExpiresAt,
+		},
+		TokenHash: authkey.HashToken(tok),
+	}
+	m.apiKeys[id] = k
+	return &APIKeyWithSecret{APIKey: *apiKeyCopy(&k.APIKey), Token: tok}, nil
+}
+
+func (m *Memory) UpdateAPIKey(tenantID, id string, patch *APIKeyPatch) (*APIKey, error) {
+	if patch == nil {
+		return nil, ErrInvalidInput
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	rec, ok := m.apiKeys[id]
+	if !ok || rec.TenantID != tenantID {
+		return nil, ErrNotFound
+	}
+	if rec.RevokedAt != nil {
+		return nil, ErrInvalidInput
+	}
+	if patch.Name != nil {
+		n := strings.TrimSpace(*patch.Name)
+		if n == "" {
+			return nil, ErrInvalidInput
+		}
+		rec.Name = n
+	}
+	if patch.Role != nil {
+		if !ValidAPIKeyRole(*patch.Role) {
+			return nil, ErrInvalidInput
+		}
+		rec.Role = strings.ToLower(strings.TrimSpace(*patch.Role))
+	}
+	if patch.ClearExpiresAt {
+		rec.ExpiresAt = nil
+	} else if patch.ExpiresAt != nil {
+		rec.ExpiresAt = patch.ExpiresAt
+	}
+	rec.UpdatedAt = time.Now().UTC()
+	return apiKeyCopy(&rec.APIKey), nil
+}
+
+func (m *Memory) RevokeAPIKey(tenantID, id string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	rec, ok := m.apiKeys[id]
+	if !ok || rec.TenantID != tenantID {
+		return ErrNotFound
+	}
+	now := time.Now().UTC()
+	rec.RevokedAt = &now
+	rec.UpdatedAt = now
+	return nil
+}
+
+func (m *Memory) RotateAPIKey(tenantID, id string) (*APIKeyWithSecret, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	rec, ok := m.apiKeys[id]
+	if !ok || rec.TenantID != tenantID {
+		return nil, ErrNotFound
+	}
+	if rec.RevokedAt != nil {
+		return nil, ErrInvalidInput
+	}
+	tok, err := authkey.GenerateToken()
+	if err != nil {
+		return nil, err
+	}
+	now := time.Now().UTC()
+	rec.TokenHash = authkey.HashToken(tok)
+	rec.Prefix = authkey.Prefix(tok)
+	rec.UpdatedAt = now
+	return &APIKeyWithSecret{APIKey: *apiKeyCopy(&rec.APIKey), Token: tok}, nil
+}
+
+func (m *Memory) ListActiveAPIKeyHashes() ([]APIKeyAuthRow, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	now := time.Now().UTC()
+	var out []APIKeyAuthRow
+	for _, rec := range m.apiKeys {
+		if rec.RevokedAt != nil {
+			continue
+		}
+		if rec.ExpiresAt != nil && !rec.ExpiresAt.After(now) {
+			continue
+		}
+		out = append(out, APIKeyAuthRow{
+			ID:        rec.ID,
+			TenantID:  rec.TenantID,
+			Role:      rec.Role,
+			TokenHash: append([]byte(nil), rec.TokenHash...),
+		})
+	}
+	return out, nil
+}
+
+func (m *Memory) TouchAPIKeyLastUsed(id string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	rec, ok := m.apiKeys[id]
+	if !ok {
+		return ErrNotFound
+	}
+	now := time.Now().UTC()
+	rec.LastUsedAt = &now
+	return nil
+}
+
+func apiKeyCopy(k *APIKey) *APIKey {
+	cp := *k
+	if k.ExpiresAt != nil {
+		t := *k.ExpiresAt
+		cp.ExpiresAt = &t
+	}
+	if k.RevokedAt != nil {
+		t := *k.RevokedAt
+		cp.RevokedAt = &t
+	}
+	if k.LastUsedAt != nil {
+		t := *k.LastUsedAt
+		cp.LastUsedAt = &t
+	}
+	return &cp
+}