Ana içeriğe geç

Authentication

SignaPort API, JWT (JSON Web Token) tabanlı authentication kullanır.

Token Türleri​

Access Token​

Geçerlilik: 15 dakika

Kullanım: Genel API erişimi için

Özellikler:

  • Bearer token olarak gönderilir
  • Header'da: Authorization: Bearer {accessToken}
  • Yenilenemez, süre dolunca yeni token alınmalı

Sign Token​

Geçerlilik: 5 dakika

Kullanım: İmzalama işlemi için

Özellikler:

  • Tek kullanımlık
  • Kullanıldığında geçersiz olur
  • Her imza için yeni token gerekir
  • SignaPort'a gönderilir

Token Alma​

Token almak için license key ve password gereklidir.

Endpoint: POST /api/v1/auth/get-token

Request:

{
  "licenseKey": "TEST-KEY-12345",
  "password": "your-password",
  "imzaTipi": 0
}

Response:

{
  "success": true,
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "signToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "accessExpiresIn": 900,
  "signExpiresIn": 300,
  "remainingQuota": 1000
}

JWT Yapısı​

JWT token üç bölümden oluşur:

header.payload.signature
{
  "alg": "HS256",
  "typ": "JWT"
}

Payload (Sign Token)​

{
  "firma_id": "TEST-FIRMA-001",
  "firma_adi": "Test Yazılım A.Ş.",
  "token_id": "abc-123-def-456",
  "imza_tipi": 0,
  "iat": 1640000000,
  "exp": 1640000300
}

Signature​

HMAC-SHA256 ile imzalanır:

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

Token Kullanımı​

Sign Token Kullanımı​

  1. get-token endpoint'inden signToken alın
  2. SignaPort'a gönderin
  3. SignaPort, validate endpoint'ini çağırır
  4. API token'ı doğrular ve kontör düşürür

Örnek:

// 1. Token al
const tokenResponse = await fetch('https://api.signaport.com/api/v1/auth/get-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    licenseKey: 'TEST-KEY-12345',
    password: 'password',
    imzaTipi: 0
  })
});

const { signToken } = await tokenResponse.json();

// 2. SignaPort'a gönder
const signRequest = {
  data: JSON.stringify({
    SignMethod: 0,
    Data: JSON.stringify({
      Token: signToken,
      PinCode: '',
      XmlFile: ['<xml>...</xml>']
    })
  })
};

Token Güvenliği​

Saklama​

Token'ları güvenli bir şekilde saklayın:

Yapın:

  • Memory'de tutun (JavaScript değişkeni)
  • Session storage kullanın (gerekirse)
  • HTTPS kullanın

Yapmayın:

  • LocalStorage'a koymayın (XSS riski)
  • Cookie'de saklamayın (CSRF riski)
  • URL'de göndermeyin (log riski)
  • Plain text dosyalara yazmayın

Token Yenileme​

Token süreleri dolduğunda yeni token alınmalı:

async function getValidToken() {
  // Cache'deki token
  if (cachedToken && !isExpired(cachedToken)) {
    return cachedToken;
  }
  
  // Yeni token al
  const response = await fetch('/api/v1/auth/get-token', {
    method: 'POST',
    body: JSON.stringify(credentials)
  });
  
  const { signToken } = await response.json();
  cachedToken = signToken;
  
  return signToken;
}

Token Doğrulama​

API, token'ı şu adımlarla doğrular:

  1. JWT formatı kontrolü
  2. Signature doğrulama
  3. Expire kontrolü
  4. Database'de kullanılmış mı kontrolü
  5. Firma aktif mi kontrolü
  6. Domain yetkisi kontrolü

Hata Durumları​

Token Süresi Dolmuş​

{
  "success": false,
  "message": "Token süresi dolmuş"
}

Çözüm: Yeni token alın

Token Kullanılmış​

{
  "success": false,
  "message": "Bu token zaten kullanılmış. Yeni token alınız."
}

Çözüm: Her imza için yeni token alın

Geçersiz Token​

{
  "success": false,
  "message": "Geçersiz token"
}

Çözüm: Token formatını ve içeriğini kontrol edin

Best Practices​

  1. Her imza için yeni token: Sign token'lar tek kullanımlık
  2. Token'ı cache etmeyin: Expire olmuş token kullanmayın
  3. HTTPS kullanın: Token sniffing'i önlemek için
  4. Error handling: Token hataları için retry mekanizması
  5. Log atmayın: Token'ları log dosyalarına yazmayın

Örnek Kod​

Token Alma (JavaScript)​

async function getSignToken(licenseKey, password, imzaTipi) {
  try {
    const response = await fetch('https://api.signaport.com/api/v1/auth/get-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ licenseKey, password, imzaTipi })
    });
    
    if (!response.ok) {
      throw new Error('Token alınamadı');
    }
    
    const data = await response.json();
    return data.signToken;
    
  } catch (error) {
    console.error('Token hatası:', error);
    throw error;
  }
}

Token Kullanma (C#)​

public async Task<LicenseResponse> ValidateToken(string token, string origin)
{
    var request = new ValidateRequest
    {
        Token = token,
        Origin = origin
    };
    
    var response = await httpClient.PostAsync(
        "https://api.signaport.com/api/license/validate",
        new StringContent(JsonConvert.SerializeObject(request))
    );
    
    return JsonConvert.DeserializeObject<LicenseResponse>(
        await response.Content.ReadAsStringAsync()
    );
}