Kahraman Olun: Quire API ile Kendi Uygulamanızı Oluşturun

Son güncelleme: 28 Mayıs 2026

Özet: Quire OAuth 2.0 API, uygulamanızın kullanıcının şifresini saklamadan onun Quire hesabı adına işlem yapmasına olanak tanır. Kayıtlı bir OAuth uygulamasına (istemci kimliği, sırrı, yönlendirme bağlantısı), dört adımlı bir yetkilendirme akışına (yapılandırma, yönlendirme, yanıtı işleme, kodu belirteçle değiştirme) ve bir yenileme belirteci döngüsüne ihtiyacınız olacak; çünkü erişim belirteçleri bir saat sonra sona erer.

Bir kullanıcının Quire verilerini okuyan veya değiştiren bir uygulama geliştirmek tek bir kararla başlar: kullanıcının şifresini hiç görmeden kimliğini nasıl doğrulayacaksınız? Quire API bu soruyu OAuth 2.0 ile yanıtlıyor. Bu yazıda OAuth uygulama kurulumunu, dört adımlı yetkilendirme akışını, erişim belirteci ve yenileme döngüsünü ve geliştiricilerin ilk geliştirmede yaptığı yaygın hataları ele alıyoruz.

Quire'ın OpenAPI 1.0.0 sürümü Ekim 2019'da yayınlandı ve o tarihten bu yana kararlı kaldı. OAuth ile kullanıcılar, uygulamanızın Quire içeriklerine (görevler, projeler, yorumlar, atamalar, etiketler, bitiş tarihleri) erişmesine yetki verir ve siz hiçbir zaman kimlik bilgilerine dokunmazsınız. Kullanıcı, şifresini değiştirmeden bu erişimi istediği zaman iptal edebilir; bu yüzden şifre saklayan entegrasyonlar OAuth onları gereksiz kılmadan önce bir güvenlik anti-deseniydi.

Hangi Quire entegrasyon yaklaşımı kullanım senaryonuza uyar?

OAuth API'yi devreye almadan önce, API'nin gerçekten doğru araç olduğundan emin olun. Quire'ın 2026'da desteklediği dört entegrasyon yüzeyi var ve her biri farklı sorunları çözüyor.

Tipik bir uygulama entegrasyonu (mobil uygulama, web panosu, senkronizasyon hizmeti) geliştiriyorsanız, isteyeceğiniz şey OAuth API'dir. Bu yazının geri kalanı bu yolda olduğunuzu varsayar.

Quire API için bir OAuth uygulamasını nasıl kurarsınız?

Quire API'yi kullanabilmek için bir OAuth uygulaması oluşturmanız gerekir.

Quire OAuth uygulamanızı oluşturun

Bir uygulama oluşturmak için Quire hesabınızda oturum açmış olmanız gerekir.

1. Quire geliştirici uygulama konsoluna gidin ve Yeni uygulama oluştur düğmesine tıklayın.

2. Uygulamanızın ait olduğu Quire Organizasyonunu seçin; organizasyon üyeleri, seçilen organizasyona ait tüm uygulamaları görüntüleyebilir/düzenleyebilir.

3. Uygulamanıza bir ad ve Yönlendirme bağlantısı verin; Yönlendirme bağlantısının rolünü daha sonra ele alacağız. Şimdilik aşağıdaki URL'yi kullanabilirsiniz:

   http://localhost:3000/callback

4. Yeni uygulama oluştur düğmesine tıklayın; yeni oluşturduğunuz OAuth uygulaması, daha fazla yapılandırmanıza olanak tanıyan geliştirici konsolu sayfasında görünecektir.

Özetle, elinizde şu üç bilgi olmalıdır:

• Geliştirme İstemci Kimliği: :wJoMEodI4fSSR54pfNwIuIzLnaJ
• Geliştirme İstemcisi Sırrı: eb8faf4nyd1wbeconw060e9ejui8zg6w8p1hyoex
• Geri arama URL'si: http://localhost:3000/callback

Quire API için geliştirme ortamınızı nasıl kurarsınız?

Adım 1. Uygulamanızı Yapılandırın

Uygulama yapılandırma bilgilerinizi uygulamanız içinde barındırın.

const clientId = ':wJoMEodI4fSSR54pfNwIuIzLnaJ';
const clientSecret = 'eb8faf4nyd1wbeconw060e9ejui8zg6w8p1hyoex';
const redirectURI = 'http://localhost:3000/callback';
  
const authorizationUrl = 'https://quire.io/oauth';
const tokenUrl = 'https://quire.io/oauth/token';
const apiUrl = 'https://quire.io/api';

Adım 2. Kullanıcıyı Quire üzerinde Uygulamayı Yetkilendirmesi için Yönlendirin

Kullanıcılarınızı Quire'ın OAuth uç noktası URI'sine yönlendireceğiniz bir yetkilendirme URL'si oluşturun. Bu, oturum açmış Quire kullanıcılarının uygulamanızı içeriklerine erişmesi için yetkilendirebileceği bir web sayfası gösterecektir.

Örnek URL:

https://quire.io/oauth?client_id=your-client-ID&redirect_uri=your-redirect-uri

Bir yetkilendirme bağlantısı görünümü örneği şuna benzeyebilir:

var http = require('http');
var url = require('url');
var server = http.createServer(function (req, res) { 
    var uri = url.parse(req.url, true);
    if (uri.pathname == '/') {        
        //..    
    } else if (uri.pathname == "/install") {
        var authUrl = authorizationUrl 
            + '?client_id=' + clientId 
            + '&redirect_uri=' + encodeURIComponent(redirectURI);
        res.writeHead(200, { 'Content-Type': 'text/html' });
        res.write(
             '<html><body>' 
            + '<a href="' + authUrl + '">Connect Quire</a>' 
         + '</body></html>');
        res.end();

    } else if (uri.pathname == "/callback") {
        //...
    }
});
server.listen(3000);

state parametresi, Siteler Arası İstek Sahteciliği (CSRF) saldırılarını önlemek için kullanılan rastgele bir dizedir. Rastgele bir karakter dizisi oluşturmalısınız. Bu, Adım 3'te değiştirilmeden uygulamanıza geri iletilecektir. Uygulamanız bu değeri doğrulamalıdır. İsteğe bağlı olmasına rağmen, bu parametreyi eklemenizi şiddetle tavsiye ederiz.

Örnek URL:

https://quire.io/oauth?client_id=your-client-ID&redirect_uri=your-redirect-uri&state=lpcl9v94z

Adım 3. OAuth 2.0 sunucusu yanıtını işleyin

OAuth 2.0 sunucusu, uygulamanızın erişim isteğine redirect_uri içinde belirtilen URL'yi kullanarak yanıt verir.

Kullanıcı erişim isteğini onaylarsa, yanıt bir yetkilendirme kodu içerir. Kullanıcı isteği onaylamazsa, yanıt bir hata mesajı içerir. Web sunucusuna döndürülen yetkilendirme kodu veya hata mesajı, aşağıda gösterildiği gibi sorgu dizesinde görünür:

Bir hata yanıtı:

http://localhost:3000/callback?error=access_denied

Bir yetkilendirme kodu yanıtı:

http://localhost:3000/callback?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

Bir geri arama örneği şuna benzeyebilir:

//...
} else if (uri.pathname == "/callback") {
   var result = uri.query;
   var message = 'Auth fail';
   if (result["error_description"] != null) {
       message = result["error_description"];
       if (result["error"] == 'access_denied') {
           //display reject message
       }
       messageView(res, message);
   } else if (result["code"] != null) {
       return exchangeAccessToken(result["code"])
       .then(function(data) {
            var token = data['access_token'];
            message = token != null ? 'Success': 'Fail';
            messageView(res, message);
        });
   }
}

Kullanıcı uygulamanızın redirect_uri'sine geri yönlendirildiğinde, sorgu dizesi parametrelerinde de bir code ve state parametresi bulunacaktır. State, isteği doğrulamak için kullandığınız CSRF sahtecilik karşıtı belirtecidir.

Sorgu dizesi parametrelerinden code ve state'i çıkarın. State bu noktada doğrulanabilir.

Bir doğrulama örneği şuna benzeyebilir:

} else if (result["code"] != null) {
    if (result["state"] != stateFromSession(res))
        return messageView(res, 'invalid state');
            
    return exchangeAccessToken(result["code"])
    .then(function(data) {
         var token = data['access_token'];
         message = token != null ? 'Success': 'Fail';
         messageView(res, message);
     });
}

Adım 4. Yetkilendirme kodunu erişim belirteciyle değiştirin

Uygulamanızın, çıkarılan yetkilendirme kodu ve aşağıdaki istek parametreleri ile belirteç uç noktasına bir POST çağrısı yapması gerekir.

Bir erişim belirteci isteği örneği şuna benzeyebilir:

var request = require('request');
function exchangeAccessToken(code) {
    return new Promise(function(resolve, reject){
        request.post({
            url: tokenUrl,
            form: {
              grant_type: 'authorization_code',
              code: code,
              client_id: clientId,
              client_secret: clientSecret,
              redirect_uri: redirectURI
            }
          },
          function (error, httpResponse, body) {
            if (error) {
              return reject(error);
            }
            resolve(JSON.parse(body))
          });
    });
}

Yanıt olarak alacağınız erişim belirteci JSON biçiminde olacaktır.

Örnek Yanıt:

{ 
  "access_token":"ACCESS_TOKEN", 
  "token_type": "bearer", 
  "expires_in":2592000, 
  "refresh_token":"REFRESH_TOKEN"
}

Her Quire API'ye erişmek için bu belirtece ihtiyacınız olduğundan dikkatlice ve kalıcı olarak saklanmalıdır.

Quire erişim belirteci ile API çağrılarını nasıl yaparsınız?

Uygulamanızın artık kullanıcı adına API çağrıları yapmak için kullanabileceği bir erişim belirteci var.

API'yi çağırın

API çağrısını, isteğin başlığında erişim belirtecini bir bearer belirteci olarak ileterek yapın.

Bir API çağrısı örneği şuna benzeyebilir:

function getCurrentUser(token) {
    return new Promise(function(resolve, reject){
        request.get({
            url: apiUrl + '/user/id/me', 
            headers: {
              "Authorization": "Bearer " + token
            }
          }, 
          function (error, httpResponse, body) {
            if (error) {
              return reject(error);
            }
            resolve(JSON.parse(body))
          });
    });
}

Örnek Yanıt:

{
  "email": "john@gmail.cc",
  "website": "https://coolwebsites.com",
  "id": "My_ID",
  "description": "This is *cool*!",
  "url": "https://quire.io/u/My_ID",
  "nameText": "My Name",
  "nameHtml": "My Name",
  "descriptionText": "This is cool!",
  "descriptionHtml": "This is <i>cool</i>!",
  "image": "https://quire.s3.amazonaws.com/oid/image.jpg",
  "iconColor": "37",
  "name": "My Name",
  "oid": "Dyh2YkFcu9uLgLFIeN1kB4Ld"
}

Süresi dolmuş bir Quire API erişim belirtecini nasıl yenilersiniz?

Bir erişim belirteci kasıtlı olarak yalnızca kısa süreli kullanım içindir. Bu, OAuth 2.0'ın önemli bir güvenlik mekanizmasıdır. Yetkilendirme Kodu İzin Akışı kullanılırken, erişim belirteçleri varsayılan olarak bir saatlik ömre sahiptir.

Bir erişim belirtecinin süresi dolduğunda, bir HTTP 401 hatası döndürülür:

{ 
  code: 401, 
  message: 'Invalid or expired token.' 
}

Your application will need to refresh the access token. 
function refreshToken(refreshToken) {
    return new Promise(function(resolve, reject){
        request.post({
            url: tokenUrl, 
            form: {
              grant_type: 'refresh_token',
              refresh_token: refreshToken,
              client_id: clientId,
              client_secret: clientSecret
            }
          }, 
          function (error, httpResponse, body) {
            if (error) {
              return reject(error);
            }
            resolve(JSON.parse(body))
          });
    });
}

Alternatif olarak, uygulamanız kullanıcıyı kimlik doğrulama akışına yönlendirebilir.

Geliştiricilerin Quire API ile yaptığı en yaygın hatalar nelerdir?

Ekiplerin Quire API'ye karşı geliştirme yapmalarını izledikten sonra, aynı beş sorunun tekrarlandığını gördük. Hiçbiri ince değil; hepsi önlenebilir.

1. İstemci sırrını istemci tarafı kodda saklamak. İstemci sırrı tam olarak budur, bir sırdır. Bir mobil uygulama ikilisinde veya bir tarayıcı paketinde sonuçlanırsa, herkes onu çıkarıp uygulamanızı taklit edebilir. Sır yalnızca kontrol ettiğiniz bir sunucuda yaşamalıdır. Uygulamanız tamamen istemci tarafıysa (tek sayfalık uygulama, mobil), sırrı gömmek yerine OAuth 2.0 PKCE akışını kullanın.

2. State parametresini doğrulamayı unutmak. state parametresi CSRF saldırılarını önlemek için vardır. Geri aramada onu doğrulamayı atlarsanız, kötü niyetli bir sitenin bir Quire hesabını saldırganın uygulama oturumuyla sessizce ilişkilendirmek için kullanabileceği bir açık bırakmış olursunuz. İstek başına state oluşturun, oturumda saklayın ve döndürülen state'in eşleşmediği her geri aramayı reddedin.

3. Erişim belirtecini kalıcı olarak ele almak. Erişim belirteçleri bir saat sonra sona erer. Belirteci saklayıp asla yenilemeyen uygulamalar 1. günde iyi çalışır ve 2. günde sessizce bozulur. Yenileme belirteci döngüsünü, "kullanıcılar şikayet ettiğinde düzeltilecek" bir yama olarak değil, herhangi bir şey yayınlamadan önce kurun.

4. Değişiklikler için API'yi yoklamak. Yoklama; hız sınırı, gecikme ve pil tüketir. Quire'daki değişikliklere tepki vermeniz gerekiyorsa bunun yerine ağ kancalarını kullanın. Ağ kancası olayı size anında iletir; bu olayı tespit etmek için yapacağınız API çağrısının hiç gerçekleşmesi gerekmez.

5. Yönlendirme bağlantısı izin listesini atlamak. Her OAuth uygulama kaydı bir yönlendirme URL'leri listesini kabul eder. Bunu joker karakterle ayarlarsanız veya kesin olarak yapılandırmayı atlarsanız, bir saldırgan kendi geri aramasını yönlendirme hedefiniz olarak kaydedebilir ve yetkilendirme kodlarını engelleyebilir. Yalnızca uygulamanızın gerçekten kullandığı tam URL'leri ekleyin.

API'ye karşı ilk kez geliştirme yapıyorsanız, kalıpları öğrenmenin en hızlı yolu mevcut bir entegrasyonu, örneğin n8n bağlayıcısını, çatallamak ve kimlik doğrulamayı, yenilemeyi ve hata durumlarını nasıl ele aldığını incelemektir.

Quire API ne zaman doğru tercih değildir?

Bunun yerine farklı bir entegrasyon yüzeyine başvurmanız gereken üç durum vardır.

• Yalnızca olaylara tepki vermeniz gerekiyor, durum sorgulamanız değil. Ağ kancaları daha basittir, itmeye dayalıdır ve yalnızca okuma amaçlı olay abonelikleri için kullanıcı yetkilendirmesi gerektirmez. Uygulamanızın görevi "bir şey olduğunda bana bildir" ise API değil ağ kancalarını kullanın.
• Bir Claude veya LLM aracısı entegrasyonu geliştiriyorsunuz. Quire MCP sunucusu buradaki doğru yüzeydir. Kimlik doğrulamayı yönetir, standart bir şema sunar ve OAuth kodunu kendinizin yazmaması anlamına gelir. MCP bunun için özel olarak tasarlanmıştır; OAuth API ile kendi çözümünüzü oluşturmak aynı sonuç için daha fazla iştir.
• Tek seferlik bir veri dışa aktarımı yapıyorsunuz. Analiz veya yedekleme için bir projenin verilerini yalnızca bir kez çekmeniz gerekiyorsa, n8n entegrasyonu veya manuel bir CSV dışa aktarımı size bir haftalık geliştirme süresi kazandırır.

Bunlardan hiçbiri geçerli değilse, OAuth API sizin aracınızdır.

Sıkça Sorulan Sorular

Quire API ücretli bir Quire planı gerektiriyor mu?

Hayır. Quire API, Free katman dahil tüm planlarda kullanılabilir. Tüm planlarda hız sınırları geçerlidir; geçerli uygulama başına sınırlar için API belgelerine bakın.

Quire API hangi programlama dillerini destekler?

API, JSON istek ve yanıt gövdeleri kullanan HTTP tabanlı bir API'dir; dolayısıyla HTTP istemcisi ve JSON ayrıştırıcısı olan herhangi bir dil çalışır. Bu yazıdaki örnekler JavaScript'tir, ancak aynı akış Python, Go, Ruby, PHP ve diğer dillerde de aynı şekilde çalışır. Resmi bir istemci kütüphanesi yoktur; API yüzeyi, dilinizin HTTP istemcisi etrafında ince bir sarmalayıcının yaygın kalıp olduğu kadar küçüktür.

Quire erişim belirteçleri ne kadar süreyle geçerlidir?

Erişim belirteçleri varsayılan olarak bir saat sonra sona erer. Yenileme belirteçleri daha uzun süre geçerlidir ve kullanıcıyı tekrar yönlendirmeden yeni erişim belirteçleri almak için kullanılabilir. Yenileme belirteci döngüsünü uygulamanıza ilk günden itibaren entegre edin.

Quire API'yi yalnızca okuma erişimi için kullanabilir miyim?

Evet. OAuth kapsamları, yalnızca uygulamanızın ihtiyaç duyduğu izinleri istemenize olanak tanır. Uygulamanız yalnızca görevleri okuyorsa, okuma kapsamlarını isteyin. Quire kullanıcıları, yetkilendirme sayfasında istenen kapsamları görür ve istek aşırı görünüyorsa reddedebilir; bu nedenle gereğinden fazla izin istemek dönüşümü olumsuz etkiler.

Quire API ile Quire MCP sunucusu arasındaki fark nedir?

API, bir kullanıcı adına Quire verilerini okumak veya değiştirmek isteyen herhangi bir uygulama için genel amaçlı bir REST yüzeyidir. MCP sunucusu ise Claude ve diğer LLM aracıları için özel olarak tasarlanmıştır: kimlik doğrulamayı yönetir, standart bir araç şeması sunar ve OAuth kodunu kendinizin yazmaması anlamına gelir. Geleneksel uygulama entegrasyonları için API'yi; LLM aracı entegrasyonları için MCP'yi kullanın.

Buradan nereye gidersiniz?

Quire API için tam OAuth 2.0 akışı budur: OAuth uygulama kurulumu, dört adımlı yetkilendirme, erişim belirteci kullanımı ve yenileme döngüsü. Geliştiricilerin çalışan bir entegrasyon yayınlayıp iki gün sonra bozulmasının en yaygın nedeni, yenileme döngüsünü ilk günden itibaren yerleşik olarak kurmak yerine sonraya bırakılacak bir düzeltme olarak ele almaktır.

Quire geliştirici uygulama konsolunda başlayın veya tam API referansını okuyun. OAuth kodu yazmamayı tercih ediyorsanız, Quire MCP sunucusu kimlik doğrulamayı sizin için yönetir ve LLM aracı entegrasyonları için doğru seçimdir. Olay tabanlı entegrasyonlar için ağ kancaları, genellikle çoğu ilk kez API entegrasyonunun ortaya çıkardığı yoklama kalıbından daha iyi bir seçimdir.