Help Center Uwierzytelnianie

Uwierzytelnianie

SMSBAT ChatHub API wykorzystuje dwupoziomowy system uwierzytelniania oparty na tokenach JWT z tokenami firmowymi i tokenami operatora.

Przepływ uwierzytelniania

graph TD
    A[Login Credentials] --> B[Get Company Token]
    B --> C[Use Company Token]
    C --> D[Get Operator Token]
    D --> E[Use Operator Token]
    E --> F[Validate Token]

Token firmy

Tokeny firmowe zapewniają dostęp na poziomie organizacji do API ChatHub.

Zdobądź token firmy

Punkt końcowy: POST /api/company/get-token

Prośba:

curl -X POST https://chatapi.smsbat.com/api/company/get-token \
  -H "Content-Type: application/json" \
  -d '{
    "login": "your-company-login",
    "password": "your-company-password"
  }'

Treść żądania:

{
  "login": "string",
  "password": "string"
}

Odpowiedź:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

Odpowiedzią jest ciąg tokenu JWT.

Użyj tokenu firmy

Dołącz token firmy do żądań API, korzystając z jednej z dwóch metod:

Metoda 1: Nagłówek autoryzacji (zalecany)

curl -X GET https://chatapi.smsbat.com/api/company/organization \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Metoda 2: Nagłówek klucza autoryzacji X

curl -X GET https://chatapi.smsbat.com/api/company/organization \
  -H "X-Authorization-Key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token operatora

Tokeny operatora zapewniają dostęp specyficzny dla użytkownika poszczególnym operatorom w organizacji.

Zdobądź token operatora

Punkt końcowy: POST /api/operator/get-token

Prośba:

curl -X POST https://chatapi.smsbat.com/api/operator/get-token \
  -H "Authorization: Bearer {company-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 123,
    "expiresAt": "2025-12-31T23:59:59Z"
  }'

Treść żądania:

{
  "id": 0,
  "expiresAt": "2025-01-20T14:33:34.147Z"
}

Parametry:

Parametr	Wpisz	Wymagane	Opis
`id`	liczba całkowita	Tak	Identyfikator operatora
`wygasa o`	ciąg znaków (ISO 8601)	Tak	Data i godzina ważności tokena (maks. 24 godziny od teraz)

Ważne: Maksymalny czas życia tokena wynosi 24 godziny. Parametr „expiresAt” nie może być dłuższy niż 24 godziny w przyszłości.

Odpowiedź:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRvcl9pZCI6MTIzLCJleHAiOjE3Mzc0MTI3OTl9.example_signature"

Użyj tokenu operatora

Dołącz token operatora do żądań API:

curl -X GET https://chatapi.smsbat.com/api/operator \
  -H "Authorization: Bearer {operator-token}"

Walidacja tokena

Przed użyciem sprawdź, czy token jest nadal ważny.

Punkt końcowy: POST /api/operator/validate-token

Prośba:

curl -X POST https://chatapi.smsbat.com/api/operator/validate-token \
  -H "Authorization: Bearer {company-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Treść żądania:

{
  "token": "string"
}

Odpowiedź (ważny token):

{
  "isValid": true,
  "operatorId": 123,
  "clientId": 0,
  "expiresAt": "2025-12-31T23:59:59Z",
  "error": null
}

Odpowiedź (nieprawidłowy token):

{
  "isValid": false,
  "error": "Invalid token"
}

Wygaśnięcie tokena

Tokeny firmowe

Brak wyraźnego wygaśnięcia w interfejsie API
Skontaktuj się ze swoim menedżerem konta, aby uzyskać zasady cyklu życia tokena
Okresowo obracaj tokeny ze względów bezpieczeństwa

Tokeny Operatora

Wygaśnięcie ustawione podczas żądania tokena (parametr expiresAt)
Zweryfikuj tokeny przed użyciem
Poproś o nowe tokeny przed wygaśnięciem

Przykłady implementacji

Pythona

import requests
from datetime import datetime, timedelta

class ChatHubAuth:
    def __init__(self, base_url):
        self.base_url = base_url
        self.company_token = None
        self.operator_tokens = {}

    def get_company_token(self, login, password):
        """Get company authentication token"""
        response = requests.post(
            f"{self.base_url}/api/company/get-token",
            json={"login": login, "password": password}
        )
        response.raise_for_status()
        self.company_token = response.json()
        return self.company_token

    def get_operator_token(self, operator_id, expires_days=30):
        """Get operator token with expiration"""
        expires_at = (
            datetime.utcnow() + timedelta(days=expires_days)
        ).isoformat() + "Z"

        response = requests.post(
            f"{self.base_url}/api/operator/get-token",
            headers={"Authorization": f"Bearer {self.company_token}"},
            json={"id": operator_id, "expiresAt": expires_at}
        )
        response.raise_for_status()

        token = response.json()
        self.operator_tokens[operator_id] = token
        return token

    def validate_token(self, token):
        """Validate if token is still valid"""
        response = requests.post(
            f"{self.base_url}/api/operator/validate-token",
            headers={"Authorization": f"Bearer {self.company_token}"},
            json={"token": token}
        )
        response.raise_for_status()
        return response.json()

# Usage
auth = ChatHubAuth("https://chatapi.smsbat.com")

# Get company token
company_token = auth.get_company_token("login", "password")

# Get operator token
operator_token = auth.get_operator_token(operator_id=123, expires_days=30)

# Validate token
is_valid = auth.validate_token(operator_token)
print(f"Token valid: {is_valid['valid']}")

JavaScript (Node.js)

const axios = require('axios');

class ChatHubAuth {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
    this.companyToken = null;
    this.operatorTokens = {};
  }

  async getCompanyToken(login, password) {
    const response = await axios.post(
      `${this.baseUrl}/api/company/get-token`,
      { login, password }
    );

    this.companyToken = response.data;
    return this.companyToken;
  }

  async getOperatorToken(operatorId, expiresDays = 30) {
    const expiresAt = new Date(
      Date.now() + expiresDays * 24 * 60 * 60 * 1000
    ).toISOString();

    const response = await axios.post(
      `${this.baseUrl}/api/operator/get-token`,
      { id: operatorId, expiresAt },
      {
        headers: {
          Authorization: `Bearer ${this.companyToken}`
        }
      }
    );

    const token = response.data;
    this.operatorTokens[operatorId] = token;
    return token;
  }

  async validateToken(token) {
    const response = await axios.post(
      `${this.baseUrl}/api/operator/validate-token`,
      { token },
      {
        headers: {
          Authorization: `Bearer ${this.companyToken}`
        }
      }
    );

    return response.data;
  }
}

// Usage
const auth = new ChatHubAuth('https://chatapi.smsbat.com');

async function authenticate() {
  // Get company token
  const companyToken = await auth.getCompanyToken('login', 'password');

  // Get operator token
  const operatorToken = await auth.getOperatorToken(123, 30);

  // Validate token
  const validation = await auth.validateToken(operatorToken);
  console.log('Token valid:', validation.isValid);
}

authenticate();

PHP

<?php

class ChatHubAuth {
    private $baseUrl;
    private $companyToken;
    private $operatorTokens = [];

    public function __construct($baseUrl) {
        $this->baseUrl = $baseUrl;
    }

    public function getCompanyToken($login, $password) {
        $ch = curl_init($this->baseUrl . '/api/company/get-token');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json'
        ]);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'login' => $login,
            'password' => $password
        ]));

        $response = curl_exec($ch);
        curl_close($ch);

        $this->companyToken = json_decode($response);
        return $this->companyToken;
    }

    public function getOperatorToken($operatorId, $expiresDays = 30) {
        $expiresAt = date(
            'Y-m-d\TH:i:s\Z',
            time() + ($expiresDays * 24 * 60 * 60)
        );

        $ch = curl_init($this->baseUrl . '/api/operator/get-token');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'Authorization: Bearer ' . $this->companyToken
        ]);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'id' => $operatorId,
            'expiresAt' => $expiresAt
        ]));

        $response = curl_exec($ch);
        curl_close($ch);

        $token = json_decode($response);
        $this->operatorTokens[$operatorId] = $token;
        return $token;
    }

    public function validateToken($token) {
        $ch = curl_init($this->baseUrl . '/api/operator/validate-token');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'Authorization: Bearer ' . $this->companyToken
        ]);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'token' => $token
        ]));

        $response = curl_exec($ch);
        curl_close($ch);

        return json_decode($response, true);
    }
}

// Usage
$auth = new ChatHubAuth('https://chatapi.smsbat.com');

// Get company token
$companyToken = $auth->getCompanyToken('login', 'password');

// Get operator token
$operatorToken = $auth->getOperatorToken(123, 30);

// Validate token
$validation = $auth->validateToken($operatorToken);
echo "Token valid: " . ($validation['isValid'] ? 'Yes' : 'No');

Najlepsze praktyki

Przechowywanie tokenów

✅ Bezpiecznie przechowuj tokeny (szyfrowana baza danych, menedżer sekretów)
✅ Nigdy nie przekazuj tokenów do kontroli wersji
✅ Użyj zmiennych środowiskowych jako poświadczeń
❌ Nie przechowuj tokenów w postaci zwykłego tekstu
❌ Nie ujawniaj tokenów w kodzie po stronie klienta

Rotacja tokenów

Okresowo obracaj tokeny firmowe (co 3-6 miesięcy)
Ustaw rozsądny termin ważności tokenów operatora (7-30 dni)
Zaimplementuj automatyczne odświeżanie tokena przed wygaśnięciem
Unieważnij tokeny, gdy operatorzy odejdą

Obsługa błędów

async function authenticateWithRetry(login, password, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await getCompanyToken(login, password);
    } catch (error) {
      if (error.response?.status === 401) {
        throw new Error('Invalid credentials');
      }

      if (i === retries - 1) throw error;

      // Wait before retry
      await new Promise(resolve =>
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
    }
  }
}

Walidacja tokena

Zawsze sprawdzaj tokeny przed krytycznymi operacjami:

async function performSecureOperation(token, operation) {
  // Validate token first
  const validation = await validateToken(token);

  if (!validation.isValid) {
    throw new Error('Token expired or invalid');
  }

  // Proceed with operation
  return await operation();
}

Względy bezpieczeństwa

Tylko HTTPS

Zawsze używaj protokołu HTTPS podczas wysyłania żądań uwierzytelnienia:

// ✅ Correct
const baseUrl = 'https://chatapi.smsbat.com';

// ❌ Wrong - never use HTTP for authentication
const baseUrl = 'http://api.chathub.smsbat.com';

Zakres tokena

Do każdej operacji użyj odpowiedniego tokena:

Token firmy: Zarządzanie organizacją, tworzenie operatorów
Token operatora: operacje na czacie, obsługa wiadomości

Ograniczanie szybkości

Zaimplementuj ograniczenie szybkości dla żądań uwierzytelnienia:

class RateLimitedAuth {
  constructor() {
    this.lastRequest = 0;
    this.minInterval = 1000; // 1 second between requests
  }

  async getToken(login, password) {
    const now = Date.now();
    const timeSinceLastRequest = now - this.lastRequest;

    if (timeSinceLastRequest < this.minInterval) {
      await new Promise(resolve =>
        setTimeout(resolve, this.minInterval - timeSinceLastRequest)
      );
    }

    this.lastRequest = Date.now();
    return await makeAuthRequest(login, password);
  }
}

Rozwiązywanie problemów

401 Nieautoryzowane

Sprawdź, czy poświadczenia są prawidłowe
Sprawdź, czy token nie wygasł — Upewnij się, że token znajduje się w nagłówkach żądań
Sprawdź format tokena

403 Zabronione

Sprawdź, czy token ma wymagane uprawnienia
Sprawdź, czy używasz prawidłowego typu tokena (firma czy operator)
Upewnij się, że token nie został unieważniony

Token wygasł

Poproś o nowy token
Zaimplementuj automatyczne odświeżanie tokena
Ustaw odpowiednie czasy ważności

Następne kroki

Organizacje - Zarządzaj organizacjami
Operatorzy - Pracuj z operatorami
Integracja widgetu - Zintegruj widget czatu

Search Results

Uwierzytelnianie

Przepływ uwierzytelniania

Token firmy

Zdobądź token firmy

Użyj tokenu firmy

Metoda 1: Nagłówek autoryzacji (zalecany)

Metoda 2: Nagłówek klucza autoryzacji X

Token operatora

Zdobądź token operatora

Użyj tokenu operatora

Walidacja tokena

Wygaśnięcie tokena

Tokeny firmowe

Tokeny Operatora

Przykłady implementacji

Pythona

JavaScript (Node.js)

PHP

Najlepsze praktyki

Przechowywanie tokenów

Rotacja tokenów

Obsługa błędów

Walidacja tokena

Względy bezpieczeństwa

Tylko HTTPS

Zakres tokena

Ograniczanie szybkości

Rozwiązywanie problemów

401 Nieautoryzowane

403 Zabronione

Token wygasł

Następne kroki