Uwierzytelnianie
Zabezpiecz każde żądanie do API AdaptlyPost kluczem API. Sprawdź, gdzie wygenerować klucze i jak wysyłać je w nagłówkach.
Klucze API
AdaptlyPost uwierzytelnia żądania REST API za pomocą kluczy API. Klucze można tworzyć i nimi zarządzać w panelu, w sekcji Zarządzaj > API i agenci AI.
Bezpieczeństwo klucza API
Klucza API nie wolno ujawniać w kodzie po stronie klienta, publicznych repozytoriach ani aplikacjach frontendowych. Klucze należy zawsze przechowywać w zmiennych środowiskowych lub bezpiecznym sejfie.Użycie klucza API
Klucz API należy podawać w nagłówku Authorization każdego żądania:
Authorization: Bearer your_api_key_herePrzykładowe żądanie
curl https://post.adaptlypost.com/post/api/v1/social-accounts \
-H "Authorization: Bearer adaptly_8f3c1d9a7b2e4605c1a8d7f36b904e2d"OAuth
Aplikacja może działać w imieniu członka bez klucza API. Wystarczy przeprowadzić przepływ OAuth z kodem autoryzacji, z PKCE lub sekretem klienta, względem logowania AdaptlyPost i wysyłać token dostępu jako Authorization: Bearer <token>. Token daje dostęp do każdego obszaru roboczego, do którego należy członek, zob. Wybór obszaru roboczego poniżej. Aby otrzymać token odświeżania, należy poprosić o offline_access. Dokument OpenAPI pod adresem GET /api/v1/openapi.json opisuje ten przepływ w securitySchemes.oauth2.
Authorize: https://harmonious-puzzle-14.authkit.app/oauth2/authorize
Token: https://harmonious-puzzle-14.authkit.app/oauth2/token
Scopes: openid profile email offline_accessRole i uprawnienia
Każdy członek obszaru roboczego ma jedną z czterech ról. Rola określa, co członek może robić w panelu oraz co może każdy klucz API, sesja MCP lub integracja działająca w jego imieniu. Weryfikacja odbywa się na serwerze przy każdym żądaniu, więc klient nie może jej obejść.
| Rola | Co może robić |
|---|---|
Administratoradmin | Wszystko w obszarze roboczym: łączy i odłącza konta społecznościowe, wybiera strony i tablice, zarządza członkami, webhookami i wszystkimi kluczami oraz robi wszystko, co Edytor. |
Edytoreditor | Tworzy, edytuje, planuje, publikuje, ponawia i usuwa posty, także innych członków. Zarządza webhookami i podpisem postów, przesyła multimedia, korzysta z AI i odczytuje analitykę. Nie może łączyć ani odłączać kont. |
Współtwórcacontributor | Tworzy i edytuje własne wersje robocze, przesyła multimedia, korzysta z AI, odczytuje posty i analitykę oraz tworzy własne klucze. Nie może planować, publikować, ponawiać ani planować zbiorczo, usuwać niczego poza własnymi wersjami roboczymi ani zmieniać postów innych członków, kont i webhooków. |
Obserwatorviewer | Odczytuje posty, połączone konta, analitykę, członków i webhooki. Nie może niczego tworzyć ani zmieniać. |
Uprawnienia według ról
Strona każdego endpointu podaje wymagane uprawnienie. Klucz ma dokładnie uprawnienia swojej roli, z wyjątkiem tych, których jego twórca już nie posiada. Listę zwraca GET /api/v1/me.
| Uprawnienie | Pozwala | Administrator | Edytor | Współtwórca | Obserwator |
|---|---|---|---|---|---|
workspace.read | Widzieć obszar roboczy | ✓ | ✓ | ✓ | ✓ |
workspace.manage | Zmieniać ustawienia obszaru roboczego | ✓ | – | – | – |
posts.read | Odczytywać posty i ich wyniki na poszczególnych platformach | ✓ | ✓ | ✓ | ✓ |
posts.draft | Tworzyć wersje robocze oraz edytować i usuwać własne wersje robocze | ✓ | ✓ | ✓ | – |
posts.others | Edytować, publikować, ponawiać i usuwać posty utworzone przez innych członków | ✓ | ✓ | – | – |
posts.schedule | Planować post na przyszły termin i edytować zaplanowany post | ✓ | ✓ | – | – |
posts.publish | Publikować od razu i ponawiać nieudane platformy | ✓ | ✓ | – | – |
posts.delete | Usuwać posty, które nie są wersjami roboczymi | ✓ | ✓ | – | – |
media.upload | Pobierać adresy URL do przesyłania obrazów i filmów | ✓ | ✓ | ✓ | – |
accounts.read | Wyświetlać połączone konta społecznościowe | ✓ | ✓ | ✓ | ✓ |
accounts.manage | Łączyć, odłączać i ponownie sprawdzać konta, wybierać strony i tablice, tworzyć linki do połączenia | ✓ | – | – | – |
analytics.read | Odczytywać analitykę | ✓ | ✓ | ✓ | ✓ |
analytics.sync | Zlecać odświeżenie analityki | ✓ | ✓ | – | – |
inbox.read | Odczytywać komentarze, wzmianki, wiadomości i opinie w skrzynce | ✓ | ✓ | ✓ | ✓ |
inbox.reply | Odpowiadać, ukrywać, polubiać, usuwać i wysyłać wiadomości w skrzynce oraz oznaczać elementy jako przeczytane lub załatwione | ✓ | ✓ | – | – |
ai.generate | Generować opisy i obrazy | ✓ | ✓ | ✓ | – |
members.read | Widzieć członków obszaru roboczego | ✓ | ✓ | ✓ | ✓ |
members.manage | Zapraszać, zmieniać i usuwać członków | ✓ | – | – | – |
tokens.own | Tworzyć i unieważniać własne klucze API | ✓ | ✓ | ✓ | – |
tokens.manage | Widzieć i unieważniać wszystkie klucze w obszarze roboczym | ✓ | – | – | – |
webhooks.read | Wyświetlać webhooki | ✓ | ✓ | – | ✓ |
webhooks.manage | Tworzyć, aktualizować, usuwać i testować webhooki | ✓ | ✓ | – | – |
signature.manage | Zmieniać podpis postów | ✓ | ✓ | – | – |
Klucze mają rolę
Rolę klucza wybiera się podczas jego tworzenia. Klucz działa następnie z tą rolą w obszarze roboczym, w którym powstał, na następujących zasadach:
- Klucza nie można utworzyć z rolą wyższą niż rola tworzącego go członka. Edytor może tworzyć klucze Edytora, Współtwórcy lub Obserwatora, ale nie Administratora.
- Przy każdym żądaniu efektywne uprawnienia klucza to uprawnienia jego roli, z wyjątkiem tych, których twórca już nie posiada. Weryfikacja uwzględnia aktualną rolę twórcy, a nie rolę z chwili utworzenia klucza.
- Jeśli twórca zostanie zdegradowany, uprawnienia wszystkich utworzonych przez niego kluczy natychmiast się zmniejszają. Klucz Edytora utworzony przez członka, który jest teraz Współtwórcą, może tylko tworzyć wersje robocze.
- Jeśli twórca opuści obszar roboczy lub zostanie z niego usunięty, jego klucze przestają działać i zwracają 401 z kodem token_issuer_lost_access. Nowy klucz tworzy administrator obszaru roboczego.
- Sesja MCP lub zgoda OAuth nie ma własnej roli: działa z rolą zalogowanego członka w obszarze roboczym, którego dotyczy wywołanie. Jest to domyślny obszar roboczy członka, chyba że X-Workspace-Id wskazuje inny.
Sprawdzenie możliwości klucza przed użyciem
Ten endpoint może wywołać każdy ważny klucz. Zwraca rolę, dokładną listę uprawnień oraz obiekt can z flagami draft, schedule i publish, dzięki czemu klient lub agent może ukryć niedozwolone działania, zamiast dowiadywać się o nich z błędu 403: GET /api/v1/meWybór obszaru roboczego
Członek może należeć do kilku obszarów roboczych, w jednej lub kilku organizacjach. Połączenie OAuth, takie jak łącznik Claude lub ChatGPT, może działać w każdym z nich. Klucz API działa tylko w obszarze roboczym, w którym został utworzony. Aby wybrać obszar roboczy, można dodać do dowolnego żądania opcjonalny nagłówek X-Workspace-Id. Bez niego wywołanie trafia do domyślnego obszaru roboczego.
X-Workspace-Id: ag_02k7mTen endpoint zwraca identyfikatory obszarów roboczych, które można wysłać, wraz z rolą i obiektem can dla każdego z nich: GET /api/v1/workspaces
Błędy uwierzytelniania
Brakujący, nieprawidłowy lub wygasły klucz zwraca 401. Klucz, który istnieje, ale nie może wykonać żądanej operacji, zwraca 403. Każda treść błędu zawiera code do odczytu maszynowego, dzięki któremu klient może je rozróżnić:
{
"statusCode": 401,
"message": "Invalid or missing API key",
"error": "Unauthorized"
}Klucz jest prawidłowy, ale członek, który go utworzył, nie należy już do obszaru roboczego. Klucz przestał działać na stałe; nowy można uzyskać od administratora obszaru roboczego.
{
"statusCode": 401,
"error": "Unauthorized",
"code": "token_issuer_lost_access",
"message": "This API key no longer works: the member who created it lost access to the workspace. Ask a workspace admin for a new key."
}Logowanie OAuth, np. przez łącznik Claude lub ChatGPT, użyło adresu e-mail bez konta AdaptlyPost. Należy odłączyć aplikację i połączyć ją ponownie, używając adresu e-mail przypisanego do konta AdaptlyPost.
{
"statusCode": 401,
"error": "Unauthorized",
"code": "oauth_account_not_found",
"message": "You signed in as jane@example.com, which has no AdaptlyPost account. Disconnect this app and connect again with the email you use on AdaptlyPost."
}Rola klucza nie obejmuje uprawnienia wymaganego do tej operacji. Treść odpowiedzi podaje brakujące uprawnienie, rolę klucza i możliwe rozwiązanie. W przypadku operacji na poście wymagane uprawnienie zależy od żądania: natychmiastowa publikacja wymaga posts.publish, przyszła wartość scheduledAt wymaga posts.schedule, a zmiana posta innego członka dodatkowo wymaga posts.others.
{
"statusCode": 403,
"error": "Forbidden",
"code": "permission_denied",
"requiredPermission": "posts.publish",
"role": "contributor",
"keyRole": "contributor",
"issuerRole": "editor",
"tokenType": "api_token",
"message": "The Contributor role cannot publish posts. Send the post with saveAsDraft: true and ask a workspace member to publish it."
}Zatrzymanie po błędzie 403
Błąd 403 z kodem permission_denied jest dla danego klucza ostateczny. Ponawianie, czekanie ani użycie innego klucza tego samego członka nie zmieni odpowiedzi. Jeśli integracja nie powinna była na niego trafić, należy poprosić administratora obszaru roboczego o klucz z rolą mającą to uprawnienie albo wysłać post z saveAsDraft: true, aby opublikował go członek z posts.publish.Plan organizacji jest nieaktywny lub nie obejmuje dostępu do API. Każde wywołanie z tym kluczem lub logowaniem OAuth otrzymuje tę odpowiedź do czasu odnowienia lub podniesienia planu. Pole code odróżnia ten błąd 403 od pozostałych.
{
"statusCode": 403,
"error": "Forbidden",
"code": "subscription_required",
"message": "This API key no longer works: your organization's plan does not include API access. Renew or upgrade the plan to use it again."
}X-Workspace-Id wskazuje obszar roboczy niedostępny dla wywołującego. Klucz API otrzymuje tę samą odpowiedź dla każdego obszaru roboczego innego niż własny. Należy wysłać identyfikator z GET /api/v1/workspaces lub pominąć ten nagłówek.
{
"statusCode": 403,
"error": "Forbidden",
"code": "workspace_access_denied",
"workspaceId": "ag_03p4r",
"message": "You have no access to workspace ag_03p4r. Call GET /workspaces to list the workspaces you can use, and send one of those ids in the X-Workspace-Id header."
}Dla zespołów podlegających regulacjom
Ograniczenia miejsca i klucza Współtwórcy są egzekwowane na serwerze, a nie w interfejsie. Każde żądanie, z panelu, REST API, serwera MCP lub integracji takiej jak Zapier czy n8n, przechodzi przez tę samą kontrolę uprawnień w usłudze postów, zanim cokolwiek zostanie zapisane: kontrola odczytuje aktualną rolę wywołującego w obszarze roboczym, ustala na podstawie faktów uprawnienie wymagane przez żądanie (wersja robocza, zaplanowanie lub natychmiastowa publikacja; własny post lub post współpracownika) i odrzuca żądanie błędem 403, jeśli uprawnienia brakuje. Klucz jest tworzony z określoną rolą, nigdy wyższą niż rola tworzącego go członka, a jego uprawnienia są przeliczane przy każdym wywołaniu jako część wspólna roli klucza i aktualnej roli twórcy, więc degradacja twórcy natychmiast ogranicza klucz, a usunięcie twórcy go unieważnia. Audytor może sprawdzić trzy rzeczy: GET /api/v1/me, który zwraca rolę i dokładną listę bieżących uprawnień klucza; treść błędu 403, która podaje brakujące uprawnienie, rolę, której go zabrakło, i rodzaj użytego tokena; oraz dziennik audytu postów, w którym każda próba utworzenia, zaplanowania, publikacji, ponowienia i usunięcia jest zapisywana wraz z informacją, kto ją wykonał, jakim kluczem, z jaką rolą, z jakiego statusu na jaki oraz czy została dopuszczona, czy odrzucona. Dziennik zapisuje usługa postów; nie jest on jeszcze dostępny w panelu ani w API.