Getting API Authorization Data

Getting the Authorization Token
Refreshing the Authorization Token
Authorization API
Endpoints
/v1/auth/token
- Parameters
- Request Example
- Response
- Errors
/v1/auth/refresh_token
- Parameters
- Request Example
- Response
- Errors

Prerequisites

Any active CStoreOffice® user account, regardless of role or permissions, can be used to authorize access to the Business Documents API. However, we recommend creating a dedicated service account specifically for API access, rather than using your existing account for the CStoreOffice® console.

If you do not have administrative permissions for CStoreOffice®, contact your system administrator to create an account for you. Refer to the information below for details on how to create an account that does not require regular password updates.

Setting an account with non-expiring password

By default, CStoreOffice® requires users to update their password every 90 days, which may not be suitable for service accounts, as frequent password changes can disrupt automated processes and integrations. To avoid interruptions and manual intervention, consider configuring an account that does not require regular password updates. This can be achieved by using a specific email address format designated for service accounts: <any text>.api@<domain name>. For example:

bd.api@acme.com
cso.api@myshop.eu

It is highly unrecommended to use email addresses that prevent automatic password expiry for common accounts, as they pose potential security risks.

Getting the Authorization Token

To get the authorization token:

Go to Authorization API:
https://api-docs.petrosoft.cloud/?service=device_gateway_proxy_service
Use the /v1/auth/token endpoint.
Click Try it out.
Send the authorization request. Request parameters:

Parameter	Description
`login`	Email address of the CStoreOffice® user.
`password`	The CStoreOffice® user password.

Receive the access_token value. It will be used as the authorization token for the Inventory Item API.

For confidentiality reasons, the token data in the images is blurred intentionally.

Refreshing the Authorization Token

After a certain period of time the authorization token expires and you need to refresh it.

To refresh the authorization token:

Go to Authorization API:
https://api-docs.petrosoft.cloud/?service=device_gateway_proxy_service
Use the /v1/auth/refresh_token endpoint.
Click Try it out.
Send the refreshing request. Request parameters:

Parameter	Description
`refresh_token`	Refresh token received from Authorization API during previous getting the authorization token or refreshing the authorization token request.

Receive the refreshed access_token value. It will be used as the authorization token for the Inventory Item API.

For confidentiality reasons, the token data in the images is blurred intentionally.

Authorization API

The Authorization API is used to generate and refresh authorization tokens for the API users. Tokens are required to get authorized with the Petrosoft APIs.

The Authorization API interacts with POST methods. To open the API, go to:
https://api-docs.petrosoft.cloud/?service=device_gateway_proxy_service.

/v1/auth/token

Use it to get the authorization token by the API user credentials.

Parameters

Parameter	Description
`login`	Email address of the CStoreOffice® user.
`password`	The CStoreOffice® user password.

Request example


{
	"login": "cso.api@mydomain.com",
	"password": "Pa$$w0rd"
}

Response

Response Code

200

Response Parameters

Parameter	Description
`access_token`	Access token to use for authorization during API requests.
`expires_in`	Access token expiration timeout in minutes.
`refresh_expires_in`	Refresh token expiration timeout in minutes.
`refresh_token`	Refresh token used to get new authorization token when previous gets expired.
`token_type`	Token type identification.
`not-before-policy`	Unique token ID.
`session_state`	Session status.

Response Example


{
	"access_token": "eyJhbGciOiJSUzI1Nixxxxxxxxxxxxxxxxxxxxxxxa3NfMG1aQW1wQm9Ea2VyNlRVT3hiMkhBUjkzRXpQYm1NIn0.eyJqdGkiOiI5NzRlMGQzYi0yOGMwLTQ3YWItYmQ4NC1kMWRkNjU3NDdlM2YiLCJleHAiOjE2NTY2NjM4NTUsIm5iZiI6MCwiaWF0IjoxNjU2NTc3NDU1LCJpc3MiOiJodHRwczovL2tjLnBldHJvc29mdC5jbG91ZC9hdXRoL3JlYWxtcy9jaxxxxxxxxxxxxxxxxxxxxxxxxx3ViIjoiMzZjYjk4ZTYtODRmZS00NzBmLWI0NWUtMjQ3NTYyYTM4NTc0IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoib2lkYyIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjIyZGYyOGY1LWNiNDQtNDI5ZS04ZTQxLWZiYjc2MmJjZTE4YyIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsiKiIsImNsb3VkLmthcHBhLnBldHJvc29mdGluYy5jb20iLCIqLmNsb3VkLmthcHBhLnBldHJvc29mdC5jbG91ZC8qIl0sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsImFkbWluIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6IiIsImFjY291bnRJZCI6NDYsImxvY2F0aW9uSWRzIjoiMTUyOSIsIm5hbWUiOiJPbGdhIE1vcmxhbmciLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJvLm1vcmxhbmdAcGV0cm9zb2Z0aW5jLmNvbSIsImdpdmVuX25hbWUiOiJPbGdhIiwiZmFtaWx5X25hbWUiOiJNb3JsYW5nIiwiZW1haWwiOiJvLm1vcmxhbmdAcGV0cm9zb2Z0aW5jLmNvbSJ9.kfaD_p5xG126V5hUZJvPV6PsLWAcA0B8pzWZUYt8omFmsgOkGxB32Wunucjbh4pfmT3M6A28dEjAJxolXp8P0uqPJGZVjhloYAYYqHw5JL78ToWq0gmukfc0eEtekiubvO0H3bqZA3V93IWu3yjwCpGQYAOg1qwYYc9nPgIKT7gW5VWKOvuX0te2I8X38xvJAmHVxeP_gd36S9WgiuKOUvc_YctindcJZpVCuBl--qCJI_Fce6qqJ4zG5OCvyBgeZSOt6WD8OCzGzMA0WNEzatQlKZvC1UzE2zp3SiEVehtATJAkIDBiTrY85y4R-SfOaWnJBzCZLq4qjC4m3q9kAA",
	"expires_in": 86400,
	"refresh_expires_in": 86400,
	"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwixxxxxxxxxxxxxxxxxxxxxxxtYjI0Zi01NGJkOGVlNWRlYzAifQ.eyJqdGkiOiI5ODQ1YmY3NC01OGM4LTQ5ZGYtYWZmNy0zNzdhY2ZkMzg5MDQiLCJleHAiOjE2NTY2NjM4NTUsIm5iZiI6MCwiaWF0IjoxNjU2NTc3NDU1LCJpc3MiOiJodHRwczovL2tjLnBldHJvc29mdC5jbG91ZC9hdXRoL3JlYWxtcy9jaxxxxxxxxxxxxxxxxxxx2tjLnBldHJvc29mdC5jbG91ZC9hdXRoL3JlYWxtcy9jaWQiLCJzdWIiOiIzNmNiOThlNi04NGZlLTQ3MGYtYjQ1ZS0yNDc1NjJhMzg1NzQiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoib2lkYyIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjIyZGYyOGY1LWNiNDQtNDI5ZS04ZTQxLWZiYjc2MmJjZTE4YyIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsImFkbWluIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6IiJ9.NRd6Kym3R-exJVDY8ZG2pwrjp0dY48mGKlTdXHyFuJY",
	"token_type": "bearer",
	"not-before-policy": 1xx0857782,
	"session_state": "2xxxxx5-cb44-429e-8e41-fxxxxxe18c",
	"scope": ""
}

Errors

400: Bad Request

401: Unauthorized

Parameter	Description
`error`	Error indicator.
`error_description`	Details for failure reason.


{
	"error": "invalid_grant",
	"error_description": "Invalid user credentials"
}

404: Not Found

500: Internal Server Error

Parameter	Description
`success`	API request success status indicator.
`data`	N/A.
`message`	Details for failure reason.
`http_code`	Error code.
`errors`	N/A.
`total`	N/A.


{
	"success": false,
	"data": [],
	"message": "Provider App\\Application\\TokenProvider\\CredentialsTokenProvider can't implement operation due restrictions.",
	"http_code": 500,
	"errors": [],
	"total": null
}

`/v1/auth/refresh_token`

Use it to refresh the authorization token by related token identifier.