REST API ve kişisel erişim token'ları

REST API, betiklere ve CI hatlarına web arayüzündeki iş akışının aynısını verir. API ile açılan bir talep aynı SQL guard’larından geçer, aynı insan onayını bekler ve tarayıcıdan açılanla aynı denetim izine düşer. Bir onaylayan karar verene kadar hiçbir şey çalışmaz.

Uç nokta referansı, depodaki OpenAPI 3.1 açıklamasıdır: docs/openapi.yaml. Bu sayfa token’ların nasıl çalıştığını anlatır ve eksiksiz bir akışı adım adım gösterir.

Yalnızca bir talep açıp onayını beklemek ve sonucu bir terminalden ya da hattan almak istiyorsanız yoklamayı qp komut satırı istemcisi sizin yerinize yapar.

Kişisel erişim token’ları

Her çağrı, bearer token olarak bir kişisel erişim token’ı taşır:

Authorization: Bearer <id>|qp_<secret>

• Token tek bir kullanıcıya aittir ve o kullanıcının web arayüzünde yapabildiğinden fazlasına izin vermez. Kapsamlar bunu yalnızca daraltabilir.
• Token her zaman sona erer. Süreyi oluştururken seçersiniz; üst sınır QUERYPROXY_API_TOKEN_MAX_DAYS gündür (varsayılan 90).
• Sahibi askıya alınır ya da silinirse token çalışmaz olur. Servis hesabı yoktur: otomasyon gerçek bir kullanıcının token’ını kullanır.
• QUERYPROXY_REQUIRE_2FA politikasının kapsadığı ve henüz iki adımlı doğrulamaya kaydolmamış bir kullanıcı API’ye erişemez: token ikinci faktörün yerini tutmamalı. Kullanıcı kaydolunca token yeniden çalışır.

Token oluşturma ve iptal etme

Profile sayfasında API tokens bölümünü açın. Token’a ad verin, kapsamlarını seçin, kaç gün geçerli olacağını yazın ve oluşturun. Değer bir kez gösterilir ve bir Copy düğmesi vardır; QueryProxy yalnızca özetini (hash) saklar, sayfayı yenilemek değeri kalıcı olarak gizler. Token’ı iptal etmek onu hemen durdurur. Oluşturma ve iptal token.created ve token.revoked olarak denetlenir.

Token oluşturmak önce onay ister:

• Yerel parolanız varsa onu girin; iki adımlı doğrulama açıksa yerine doğrulayıcı uygulamanızdaki kodu girin. Yanlış denemeler istek sınırına tabidir.
• Yerel parolası olmayan (yalnızca SSO) bir hesap, son 15 dakika içinde SSO ile girmiş olmalıdır. Aksi hâlde sayfa sizi yeniden SSO’ya gönderir ve geri getirir.

Kapsamlar

Profile sayfası yalnızca rollerinizin kullanabildiği kapsamları sunar.

API’nin koruduğu kurallar

• Onay atlanamaz. Talep, web arayüzündeki gibi bir insan kararını bekler.
• Override yoktur. Override olacak bir onay (onaylayan, talebin takımında DBA olmayan bir sistem yöneticisi ya da talep sahibinin kendisi) yazılı gerekçe ister. API bunu 403 ile ve web formuna giden bir override_url ile reddeder. API’nin kendi override yolu yoktur.
• Bir token, sahibinin kendi talebini asla onaylayamaz.
• Sonuçlar maskelenir; bağlantının maskeleme kurallarıyla, her yerdeki gibi. Sonucun kolon adları sonuç verisidir: Auditor onları alamaz, sonucu da hiç okuyamaz.
• Auditor’lar redakte edilmiş SQL görür. SQL’in literal değerlerini görmemesi gereken biri için sql_original ve sql_prepared null gelir; sql_redacted ifadeyi literaller değiştirilmiş hâlde taşır.

Bir onaylayanın sızdırılmış token’ı, approvals:write kapsamı içinde başka kullanıcıların taleplerini yine de onaylayabilir; bu yüzden bu kapsamı az verin ve süreyi kısa tutun.

İstek sınırları

Her token dakikada QUERYPROXY_API_RATE_LIMIT çağrı yapabilir (varsayılan 60). Aşılırsa API, Retry-After başlığıyla 429 döner. Başarısız kimlik doğrulamalar adres başına aynı sayıyla sınırlanır. Yanıtlar X-RateLimit-Limit ve X-RateLimit-Remaining başlıklarını taşır.

curl ile adım adım

Örnekler iki değişken varsayar: QP kurulumunuzun adresi, TOKEN token değeri.

export QP=https://queryproxy.example.com
export TOKEN='7|qp_...'

1. Bağlantıyı bulun. GET /api/v1/connections, kullanabildiğiniz bağlantıları host ve kimlik bilgisi olmadan listeler.

curl -s -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
  "$QP/api/v1/connections"

2. Talebi gönderin. requests:submit ister. connection_id ve sql zorunludur; title (en fazla 150 karakter) ve reason (en fazla 1000) isteğe bağlıdır. Yanıt 201’dir ve talep pending durumundadır.

curl -s -X POST "$QP/api/v1/requests" \
  -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"connection_id": 3, "sql": "SELECT id, status FROM orders", "title": "Orders check", "reason": "Support ticket"}'

SQL guard ifadeyi 422 ve bir violations listesiyle reddedebilir. Göremediğiniz bir bağlantı 404 olarak bildirilir; görebildiğiniz ama gönderemeyeceğiniz bir bağlantı (Auditor ya da yazma için read tanımlaması) 403 ile reddedilir.

3. Talebi izleyin. requests:read ister. status completed olana (ya da failed, rejected, cancelled) kadar sorgulayın. Durumlar: pending, approved, rejected, queued, running, completed, failed ve cancelled.

curl -s -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
  "$QP/api/v1/requests/42"

4. Onay. Takımın bir DBA’i (talep sahibi değil) web arayüzünde, Slack ya da Teams’te veya approvals:write kapsamlı kendi token’ıyla (aşağıda REVIEWER_TOKEN) API üzerinden onaylar:

curl -s -X POST -H "Authorization: Bearer $REVIEWER_TOKEN" -H 'Accept: application/json' \
  "$QP/api/v1/requests/42/approve"

curl -s -X POST "$QP/api/v1/requests/42/reject" \
  -H "Authorization: Bearer $REVIEWER_TOKEN" -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"reason": "Add a WHERE clause"}'

Karara bağlanmış bir talep 409 döner. Talep sahibi bekleyen talebini POST /api/v1/requests/42/cancel ile geri çekebilir.

5. Sonucu okuyun. results:read ister. Varsayılan NDJSON’dur: satır başına bir JSON dizisi, değerler kolon sırasıyla (kolon adları talebin result.columns alanındadır). Başlık satırlı CSV için Accept: text/csv gönderin.

curl -s -H "Authorization: Bearer $TOKEN" "$QP/api/v1/requests/42/result"

curl -s -H "Authorization: Bearer $TOKEN" -H 'Accept: text/csv' \
  "$QP/api/v1/requests/42/result" -o result.csv

X-QueryProxy-Row-Count ve X-QueryProxy-Truncated yanıt başlıkları kaç satırın saklandığını ve sonucun satır tavanında kesilip kesilmediğini söyler. Tamamlanmamış, başarısız olmuş ya da sonucu silinmiş bir talep 409 döner; 404, saklanan dosyanın sonuç diskinde bulunmadığı anlamına gelir. Her okuma result.downloaded olarak denetlenir.

Hatalar

Hatalar message içeren JSON’dur. Doğrulama hataları (422) alan bazında anahtarlanmış errors ekler.

Denetim günlüğünde

API ile yapılan gönderimler, onaylar, retler, iptaller ve sonuç okumaları channel = api taşır. Token oluşturma ve iptal token.created ve token.revoked olarak kaydedilir. Bkz. Denetim zinciri ve SIEM aktarımı.

Ayarlar

Sonraki adımlar

• Bu API’nin hazır komut satırı istemcisi için qp istemcisi.
• Kimin neyi onaylayabileceği için Onay akışı.
• Kullanıcılarınız bir sağlayıcıyla giriyorsa Tek oturum açma.
• Token hijyeni için Üretim güvenliği.