Authorization

To get started, do the following:

Create an account in Pyrus. We recommend using bots to work with the API. Bots are technical accounts that can't use the web or mobile applications. You can find detailed instructions for creating bots in this article.
Log in to the profile, open the Authorization section, and copy the API access key — security_key. If the user does not have one yet, press the button Get new security key.
Perform the authorization request auth. It returns access_token, which must be specified in every subsequent request.
In Cloud Pyrus, the reply to the request for authorization auth contains an api_url and files_url — of the API address and file service that you need to use to work with Pyrus API with the received access_token.

Note: if you use the cloudless version of Pyrus — Pyrus Datacenter — send the authorization request to your server, not to accounts.pyrus.com: POST https://pyrus.yourdomain.org/api/v4/auth, where pyrus.yourdomain.org is your corporate domain where Pyrus Datacenter is deployed. accounts.pyrus.com is the Cloud Pyrus sign-in service; it doesn't work with Pyrus Datacenter accounts.

In Pyrus Datacenter, the reply to the authorization request doesn't contain api_url and files_url. All API methods are available at https://pyrus.yourdomain.org/api/v4/ — use this address with the received access_token. For more details, see Endpoints.

Pyrus Tip: if you use your account for testing and development purposes, you can create an API access key in your profile.

Note: to work reliably, your application must be able to re-request a token from the API access key.

Pyrus Tip: if you have more than one account registered to the same email, then to receive a token you need to add the person_id parameter, where person_id is equal to the employee ID.

{
   "login": "YOUR EMAIL",

   "security_key": "SECRET KEY",

   "person_id": 16900
}

POST /auth

POST https://accounts.pyrus.com/api/v4/auth

Request body

{
    "login": "bill.smith@somedomain.edu",
    "security_key": "czSHwEAthJKMshQ*****"
}

Response body

{
   "access_token": "gAAAAA15vmSeoj*****",
   "api_url": "https://api.pyrus.com/v4/",
   "files_url": "https://files.pyrus.com/"
}

curl

curl -X POST \
  https://accounts.pyrus.com/api/v4/auth/ \
  -H 'Content-Type: application/json'
  -d '{
    "login": "<YOUR_LOGIN>",
    "security_key": "<YOUR_SECURITY_KEY>"
}'

In Pyrus Datacenter, replace https://accounts.pyrus.com/api/v4/auth in the request with https://pyrus.yourdomain.org/api/v4/auth.

Parameters

login	Bot's login
security_key	Security Key, obtained on step 2

Using the token

The obtained token must be specified in the HTTP Authorization header for each API request:

Authorization: Bearer gAAAAA15vmSeoj*******

The token lifetime is limited, so your application must be able to reauthorize if the token has been revoked.

Revoking tokens

Access tokens can be revoked in the following cases:

The token has expired.
The maximum number of tokens per user has been exceeded. If the limit is reached, creating a new token automatically invalidates the oldest token.
The user has changed security_key in his profile. In this case, all tokens issued with the obsolete security key will be revoked.
The user has changed his password.
The user's account has been blocked.