Authentication

API methods that work with your data require a token. Send the token in the HTTP header:

Authorization: Bearer your_token

Without a valid token, protected methods return an unauthorized error (see Errors).

There are two ways to get a token:

API tokens (recommended)

Creating in the web app

1. Open Settings → API tokens.
2. Click Create token.
3. Enter the Token name (required, up to 128 characters).
4. Optionally turn on Read-only (disallows mutations): with such a token queries (query) work, and any mutation is rejected.
5. Copy the secret and store it.

The token list shows the name, creation date, and last-used time. You can Rename or Revoke a token. A revoked token stops working.

Creating via the API

You can also create a token with the createApiToken mutation (like any mutation, it is not available with a read-only token):

mutation {
  createApiToken(name: "Publishing script", readOnly: false) {
    tokenValue
    token {
      id
      name
      readOnly
      active
      createdAt
    }
  }
}

In the response, tokenValue is the secret (shown only in this response) and token is the token metadata.

List your tokens and manage them:

query {
  apiTokens {
    id
    name
    readOnly
    active
    createdAt
    lastUsedAt
  }
}

mutation {
  updateApiToken(tokenId: "token_id", name: "New name")
}

mutation {
  revokeApiToken(tokenId: "token_id")
}

The secret is never returned by apiTokens.

Rate limit

Requests made with an API token are rate limited: by default 600 requests per minute per token (the window is a UTC calendar minute). When exceeded, the server responds with HTTP status 429 Too Many Requests; retry in the next minute.

Alternative: the login mutation

The login mutation does not need a token and returns a token for your ParrotPoster email and password.

mutation {
  login(
    input: {
      username: "your-email@example.com"
      password: "your-password"
      from: FRONT
    }
  ) {
    token
    userId
  }
}

Allowed Platform values: FRONT, BITRIX, BITRIX_24, WORDPRESS. Values other than FRONT are meant for the official plugins.

Response:

{
  "data": {
    "login": {
      "token": "your_token",
      "userId": "user_id"
    }
  }
}

Pass a login token the same way as an API token: Authorization: Bearer <token>.

How a login token behaves

• The token has no expiry: it works until it is revoked.
• Such a token appears in Settings → Sessions (where you can end the session) and is revoked with the revokeToken mutation. Called without arguments, it revokes the token sent in the header:

mutation {
  revokeToken
}

• The limit of 600 requests per minute applies only to API tokens; it does not apply to tokens from login.
• A login token has full access: there is no read-only mode for it. If you need restricted access, use an API token.

Storing the token

1. Store the token in a secure place (environment variables, CI secrets), not in a repository.
2. Do not put the token in client-side code (JavaScript on site pages): the token gives access to your account.
3. Create a separate token for each integration so you can revoke it independently of the others.

Examples

cURL

curl -X POST https://parrotposter.com/api/graphql \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { listSocialAccounts { id name } }"}'

PHP

<?php
$ch = curl_init('https://parrotposter.com/api/graphql');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'query' => 'query { listSocialAccounts { id name } }',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);