Getting Started

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:

Nagłówek Authorization
Authorization: Bearer your_api_key_here

Przykł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.

Endpointy OAuth
Authorize: https://harmonious-puzzle-14.authkit.app/oauth2/authorize
Token:     https://harmonious-puzzle-14.authkit.app/oauth2/token
Scopes:    openid profile email offline_access

Role 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ść.

RolaCo może robić
AdministratoradminWszystko 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.
EdytoreditorTworzy, 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órcacontributorTworzy 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.
ObserwatorviewerOdczytuje 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.

UprawnieniePozwalaAdministratorEdytorWspółtwórcaObserwator
workspace.readWidzieć obszar roboczy✓✓✓✓
workspace.manageZmieniać ustawienia obszaru roboczego✓–––
posts.readOdczytywać posty i ich wyniki na poszczególnych platformach✓✓✓✓
posts.draftTworzyć wersje robocze oraz edytować i usuwać własne wersje robocze✓✓✓–
posts.othersEdytować, publikować, ponawiać i usuwać posty utworzone przez innych członków✓✓––
posts.schedulePlanować post na przyszły termin i edytować zaplanowany post✓✓––
posts.publishPublikować od razu i ponawiać nieudane platformy✓✓––
posts.deleteUsuwać posty, które nie są wersjami roboczymi✓✓––
media.uploadPobierać adresy URL do przesyłania obrazów i filmów✓✓✓–
accounts.readWyś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.readOdczytywać analitykę✓✓✓✓
analytics.syncZlecać odświeżenie analityki✓✓––
inbox.readOdczytywać komentarze, wzmianki, wiadomości i opinie w skrzynce✓✓✓✓
inbox.replyOdpowiadać, ukrywać, polubiać, usuwać i wysyłać wiadomości w skrzynce oraz oznaczać elementy jako przeczytane lub załatwione✓✓––
ai.generateGenerować opisy i obrazy✓✓✓–
members.readWidzieć członków obszaru roboczego✓✓✓✓
members.manageZapraszać, zmieniać i usuwać członków✓–––
tokens.ownTworzyć i unieważniać własne klucze API✓✓✓–
tokens.manageWidzieć i unieważniać wszystkie klucze w obszarze roboczym✓–––
webhooks.readWyświetlać webhooki✓✓–✓
webhooks.manageTworzyć, aktualizować, usuwać i testować webhooki✓✓––
signature.manageZmieniać 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/me

Wybó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.

Nagłówek obszaru roboczego
X-Workspace-Id: ag_02k7m

Ten 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ć:

401 Unauthorized
{
  "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.

401 Unauthorized: twórca utracił dostęp
{
  "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.

401 Unauthorized: brak 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.

403 Forbidden: brak uprawnień
{
  "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.

403 Forbidden: wymagana subskrypcja
{
  "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.

403 Forbidden: brak dostępu do obszaru roboczego
{
  "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.