İçeriğe geç
ajan.io

Belgeler menüsü

Bu sayfada

Auth yapılandırmasını güncelle

Özel bir entegrasyon için kimlik doğrulamayı yapılandırın

Bir entegrasyon için kimlik doğrulama yöntemini yapılandırır. Kullanıcıların harici servise nasıl bağlanacağını belirler — API key, OAuth, service account veya kimlik doğrulama olmadan.

Başlamadan önce

  • Changing authType: authType değiştirmek bu entegrasyona ait tüm mevcut kullanıcı bağlantılarını siler. Kullanıcıların yeniden bağlanması gerekir.

Base URL

https://api.ajan.io/integrations/v1/{integrationId}/auth

Dedicated deployments Tüm isteklerde api.ajan.com'u /api/public ile değiştirin.

Required Scopes

Bu endpoint INTEGRATION_API kapsamı gerektirir.

Parameters

Path Parameters

ParameterTypeRequiredDescription
integrationIdstringYesEntegrasyonun UUID'si

Request Body

ParameterTypeRequiredDescription
authTypestringYesKimlik doğrulama yöntemi (aşağıdaki Auth Types)
authFieldsarrayNoBağlanırken kullanıcıların doldurduğu alanlar (Auth Field Schema)
authTestCodestringNoKimlik bilgilerini doğrulayan JavaScript kodu (maks. 1.000 karakter)
oauthClientobjectNoOAuth yapılandırması (yalnızca OAUTH / OAUTH_DCR için)

Auth Types

TypeDescription
NONEKimlik doğrulama gerekmez
API_KEYKullanıcılar özel auth alanlarıyla kimlik bilgisi sağlar
OAUTHYetkilendirme kodu ile OAuth 2.0 akışı
OAUTH_DCRDynamic Client Registration ile OAuth 2.0

Auth Field Schema

Her auth alanı, kullanıcıların entegrasyona bağlanırken doldurduğu bir kimlik bilgisi girişini tanımlar.

PropertyTypeRequiredDescription
slugstringYesAlan için benzersiz tanımlayıcı (maks. 100 karakter)
labelstringYesGörünen etiket (maks. 100 karakter)
typestringYesGiriş türü (aşağıdaki Field Types)
descriptionstringNoYardım metni (maks. 500 karakter, varsayılan: "")
placeholderstringNoPlaceholder metni (maks. 200 karakter)
requiredbooleanNoAlanın zorunlu olup olmadığı (varsayılan: false)

slug entegrasyon içinde benzersiz olmalıdır. Alan id'si otomatik üretilir — isteğe dahil etmeyin.

Field Types

TypeDescription
TEXTTek satırlı metin girişi
MULTI_LINE_TEXTÇok satırlı metin girişi
PASSWORDMaskeli parola girişi
NUMBERSayısal giriş
EMBEDDING_MODELEmbedding model seçici

OAuth Client Schema

Yalnızca authType OAUTH veya OAUTH_DCR olduğunda geçerlidir.

PropertyTypeRequiredDescription
scopesstringNoBoşlukla ayrılmış OAuth scope'ları (maks. 2.000 karakter)
authUrlstringNoAuthorization endpoint URL
tokenUrlstringNoToken endpoint URL
clientIdstringNoOAuth client ID (maks. 500 karakter)
clientSecretstringNoOAuth client secret (maks. 500 karakter, yalnızca yazma)
labelstringNoBağlan düğmesi için görünen etiket (maks. 100 karakter)
authorizationCodestringNoÖzel authorization kodu (maks. 1.000 karakter)
accessTokenCodestringNoÖzel access token kodu (maks. 1.000 karakter)
refreshTokenCodestringNoÖzel refresh token kodu (maks. 1.000 karakter)

OAuth kimlik bilgileri (clientId, clientSecret, authUrl, tokenUrl) yalnızca yazılabilir — API yanıtlarında asla döndürülmez.

Example: API Key Authentication

javascript
const axios = require("axios");

async function configureAuth(integrationId) {
  const response = await axios.patch(
    `https://api.ajan.io/integrations/v1/${integrationId}/auth`,
    {
      authType: "API_KEY",
      authFields: [
        {
          slug: "api_key",
          label: "API Key",
          type: "PASSWORD",
          description: "Your API key from the service dashboard",
          placeholder: "sk-...",
          required: true
        },
        {
          slug: "base_url",
          label: "Base URL",
          type: "TEXT",
          description: "API base URL",
          placeholder: "https://api.example.com",
          required: true
        }
      ],
      authTestCode: `
        const response = await ld.request({
          method: "GET",
          url: data.auth.base_url + "/me",
          headers: { Authorization: "Bearer " + data.auth.api_key }
        });
        if (response.status < 200 || response.status >= 300) {
          throw new Error("Invalid credentials");
        }
        return { success: true };
      `
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Auth configured:", response.data.integration);
}

configureAuth("550e8400-e29b-41d4-a716-446655440000");

Response Format

Success Response (200 OK)

typescript
{
  integration: {
    id: string;
    authType: string;
    authTestCode: string | null;
    authFields: Array<{
      slug: string;
      label: string;
      type: string;
      description: string;
      placeholder: string | null;
      required: boolean;
    }>;
    oauthClient: {
      scopes: string | null;
      label: string | null;
      authorizationCode: string;
      accessTokenCode: string;
      refreshTokenCode: string;
    } | null;
  };
}

Behavior

  • Auth alanları her çağrıda tamamen değiştirilir — dizi silinir ve yeniden oluşturulur.
  • authType değiştirmek tüm mevcut kullanıcı bağlantılarını ve önceki OAuth client yapılandırmasını siler.
  • authType'ı NONE, API_KEY veya SERVICE_ACCOUNT yapmak mevcut OAuth client'ı siler.
  • OAuth kimlik bilgileri (clientId, clientSecret) saklanmadan önce şifrelenir.

Error Handling

Status CodeDescription
400Geçersiz istek gövdesi veya entegrasyon ID
401Geçersiz veya eksik API anahtarı
403Bu entegrasyona erişim yok
404Entegrasyon bulunamadı
429Rate limit aşıldı
500İç sunucu hatası

ajan, API anahtarınızı korumak ve uygulamalarınızın güvenliğini sağlamak için tarayıcı kaynaklı istekleri bilinçli olarak engeller. Daha fazla bilgi için API Key Best Practices kılavuzuna bakın.