Autoryzacja
Typy użytkowników i uprawnienia
Każde wywołanie usługi API wymaga autoryzacji użytkownika. Użytkownikiem autoryzującym się jest dowolne konto pocztowe obsługiwane przez serwer. Użytkownicy API dzielą się na 2 grupy:
- administratorzy domen - reprezentowani przez każde konto postmaster@<domena_pocztowa>
- zwykłe konta - reprezentowane przez dowolne inne konto pocztowe
Administrator domeny może wykonać dowolną przewidzianą przez API operację w obrębie własnej domeny pocztowej, czyli:
- odczytywać i modyfikować ustawienia domeny pocztowej
- odczytywać, dodawać, modyfikować, usuwać dowolne konto pocztowe, alias lub listę pocztową
Zwykłe konto pocztowe może:
- odczytywać swoje ustawienia
- modyfikować swoje ustawienia z wyjątkiem tych, których modyfikacja wymaga uprawnień administratora tj.:
- wszelkiego rodzaju limitów (zajętości, aliasów, przekierowań)
- opisu konta
- daty ważności konta
- flagi blokady konta
Uwaga! Usługa API pozwala na połączenia tylko od klienta działającego na tym samym adresie IP co ona (wywołania wewnątrz vps). Jeśli jest zapotrzebowanie na połączenie z innych adresów IP należy ten fakt zgłosić do biura obsługi klienta.
Dane autoryzacyjne
Proces autoryzacji opiera się na następujacych danych:
- pełen adres email użytkownika
- skrót sha1 hasła użytkownika
Informacje te powinny zostać przekazane do usługi API w nagłówku Authorization żądania HTTP, którego ogólna postać to:
Authorization: Basic <BASE64_HASH>
gdzie <BASE64_HASH> to wynik wyrażenia: base64_encode(<konto_email>:sha1(<haslo-konta>)).
Przykłady
Użytkownikiem usługi API jest konto postmaster@demo.kei.pl posiadające hasło 1vLmtlaS5wbDpmZmIyZ. Wygenerowanie odpowiedniego hash'a w języku PHP będzie wyglądać następująco:
$authHash = base64_encode( 'postmaster@demo.kei.pl:' . sha1('1vLmtlaS5wbDpmZmIyZ') );
Pełen nagłówek Authorization będzie mieć postać:
Authorization: Basic cG9zdG1hc3RlckBkZW1vLmtlaS5wbDo5MTRlMjA5YmE3OTE1MTU2ZDEwYTdlOTVhOWU1ZGNiYmQwZDczMWVh
Przykładowe żądanie HTTP do usługi API wraz z nagłówkiem autoryzującym:
GET /v1/emails/demo.kei.pl/postmaster HTTP/1.1 Host: as27.kei.pl Accept: */* User-Agent: API-CLIENT X-Forwarded-For: 195.149.224.27 Content-Type: application/json Authorization: Basic cG9zdG1hc3RlckBkZW1vLmtlaS5wbDo5MTRlMjA5YmE3OTE1MTU2ZDEwYTdlOTVhOWU1ZGNiYmQwZDczMWVh