How Pyrus interacts with the extension service
Pyrus interacts with the extension service based on webhooks (requests from Pyrus to the extension service) and methods of the Extensions API (requests from the extension service to Pyrus).
Access to Extensions API
Extensions API methods are available at https://extensions.pyrus.com/v1/. To authorize requests, you need to make a POST token request and obtain an access token. The token you receive must be specified in the HTTP Authorization header for each API request:
Authorization: Bearer gAAAAA15vmSeoj*******
The token has a limited validity period, so your application should be able to re-authenticate if the token is revoked. The authorization token may be revoked in the following cases:
- the token has expired;
- the secret key of your extension has been revoked by the Pyrus administrator or security service. If this happens, all issued tokens will be revoked.
General requirements
Parameters of POST requests are passed in the request body in JSON format. Parameters of GET requests are passed in the URL and, if special characters are present, they must be escaped using urlencode. All responses are passed in the response body in JSON format. When passing numbers, a period is used as the separator between the integer and decimal parts. Dates are passed in ISO 8601 format. The response from the server always comes with a zero time zone. Empty fields are not returned in the response. In case of an error, the response body should include the fields:
- error — error message;
- error_code — error code string.
In case of an erroneous call, the most appropriate HTTP Status Code is returned.
Accessibility of your service
After publishing a new version of the extension (or when testing it), Pyrus will start sending requests about user actions to the address specified on the main settings page in the developer's personal account (PA). Pyrus also periodically sends a pulse request to check the availability of your service.
Your web service must respond to the call with a 2xx status to all requests within 10 seconds. If your service is unavailable or responds with a status other than 2xx, Pyrus will send a second request after 11 seconds, and then a third one after 22 seconds. The attempt number is contained in the X-Pyrus-Retry header. The value is one of three: "1/3", "2/3", or "3/3". The numerator is the attempt number, starting from one, and the denominator is the number of attempts (three attempts). The value "1/3" is set for the first call. If it is not possible to connect in three attempts, Pyrus will update the status of the published extension version to Technical Failure, making it unusable. You will receive a notification at the email specified in the general extension settings. Pyrus will continue to send heartbeat requests to your service. Once your service becomes available, Pyrus will update the status of the extension version to Published.
Signature verification
To ensure that the request was sent by Pyrus and not someone else, the requests contain the X-Pyrus-Sig header, whose value indicates the signature of the request. To verify the signature, you need to add the extension's secret key to the request body, calculate the HMAC digest for the resulting string using the SHA1 algorithm, and compare it to the value in the X-Pyrus-Sig header. Examples of implementing signature verification in different programming languages can be found here.
Authorizing in the extension system
When installing the extension, the user must be authorized in an external system. Pyrus supports two methods of authorization.
Authorizing via access keys
When logging in to an external system via access keys, the user is prompted to enter parameters for authorization on the main settings page of the extension in the Authorization by Parameters block in the Pyrus account. This sends an authorize request to your service, containing the user-entered data. Pyrus learns the authorization results from the response.
Authorizing via OAuth 2.0 protocol
When authorizing via the OAuth 2.0 protocol, a new tab opens in the user's browser with a link for authorization in the external system specified on the main settings page in the Authorization by OAuth 2.0 block in their Pyrus account. An additional text parameter called state is added to the end of the link. This parameter is necessary for further authorization in Pyrus. After logging in successfully, you need to redirect the user to the address https://pyrus.com/, where state_string is the string passed by Pyrus when opening the authorization link, and token is the authorization code. Pyrus then sends an authorize request to your service, with the received authorization code. Furthermore, the request body will include additional fields such as client_id, client_secret, scope, if filled, a redirect_uri parameter with the value https://pyrus.com/integrations/oauthorization, and a grant_type parameter with the value access_token for authorization or refresh_token for access restoration. The response body should contain an authorization token that Pyrus will use in requests to your service, and a refresh token for updating the authorization token. Pyrus updates the authorization token if the error_code field in the response of any of the webhooks for extensions shows an expired_token error.
Enabling/disabling extension
The user can pause the extension account in order to not receive notifications about new events. In that case, Pyrus sends a POST toggle request to your service. If the account is paused, Pyrus will ignore all notifications about new events for this account, so, to avoid being blocked due to exceeding the request limit, it is worthwhile to stop the sending of notifications about new events for disabled accounts.