Аутентификация

Методы API, работающие с вашими данными, требуют токен. Токен передаётся в HTTP-заголовке:

Authorization: Bearer ваш_токен

Без корректного токена защищённые методы возвращают ошибку unauthorized (см. Ошибки).

Получить токен можно двумя способами:

API-токены (рекомендуется)

Создание в кабинете

1. Откройте Настройки → API-токены.
2. Нажмите Создать токен.
3. Укажите Название токена (обязательно, до 128 символов).
4. При необходимости включите Только чтение (без мутаций): с таким токеном доступны запросы (query), а любая мутация будет отклонена.
5. Скопируйте секрет и сохраните его.

В списке токенов видно название, дату создания и время последнего использования. Токен можно Переименовать или Отозвать. Отозванный токен перестаёт работать.

Создание через API

Токен можно создать и мутацией createApiToken (она, как и любая мутация, недоступна из-под токена «только чтение»):

mutation {
  createApiToken(name: "Скрипт публикации", readOnly: false) {
    tokenValue
    token {
      id
      name
      readOnly
      active
      createdAt
    }
  }
}

В ответе tokenValue — секрет (показывается только в этом ответе), token — метаданные токена.

Список своих токенов и управление ими:

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

mutation {
  updateApiToken(tokenId: "token_id", name: "Новое название")
}

mutation {
  revokeApiToken(tokenId: "token_id")
}

Секрет в apiTokens не возвращается никогда.

Лимит запросов

На запросы по API-токену действует лимит частоты: по умолчанию 600 запросов в минуту на один токен (окно — календарная минута UTC). При превышении сервер отвечает HTTP-статусом 429 Too Many Requests; повторите запрос в следующую минуту.

Альтернатива: мутация login

Мутация login не требует токена и возвращает токен по email и паролю ParrotPoster.

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

Допустимые значения Platform: FRONT, BITRIX, BITRIX_24, WORDPRESS. Значения, кроме FRONT, предназначены для официальных плагинов.

Ответ:

{
  "data": {
    "login": {
      "token": "ваш_токен",
      "userId": "user_id"
    }
  }
}

Токен из login передаётся так же, как API-токен: Authorization: Bearer <token>.

Поведение токена login

• Токен не имеет срока действия: он работает, пока его не отозвали.
• Такой токен виден в Настройки → Сеансы (там можно завершить сеанс) и отзывается мутацией revokeToken. Вызванная без аргумента, она отзывает токен, переданный в заголовке:

mutation {
  revokeToken
}

• Лимит частоты 600 запросов в минуту относится только к API-токенам; на токены из login он не распространяется.
• Токен из login — полнодоступный: режима «только чтение» у него нет. Если нужен ограниченный доступ, используйте API-токен.

Хранение токена

1. Храните токен в защищённом месте (переменные окружения, секреты CI), не в репозитории.
2. Не вставляйте токен в клиентский код (JavaScript на страницах сайта): токен даёт доступ к вашему аккаунту.
3. Для каждой интеграции создавайте отдельный токен — так его можно отозвать независимо от остальных.

Примеры

cURL

curl -X POST https://parrotposter.com/api/graphql \
  -H "Authorization: Bearer ваш_токен" \
  -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);