Authorization in Sailplay API

This section describes the rules and procedures for obtaining and securely using primary identifiers and a token to work with the Sailplay platform's REST API.

The API authorization process consists of 2 simple steps:

1. Get primary identifiers in your Sailplay account
2. Make an API request to get a token

---

Main API authorization parameters

Parameter	Description
store_department_id	A unique numeric identifier for the Department. Used in the token request as well as in all subsequent API requests.
store_department_key	The numeric secret key of the Department. It is used only to get a token in the /api/v2/login/ request.
pin_code	A numeric code assigned to a specific Employee. To get a token in the /api/v2/login/ request, it is recommended to use the value of the service account of the employee.
token	A 40-character hex-identifier returned by the /api/v2/login/ method. It signs all further requests to the API.

---

Getting primary identifiers

1. Get identifiers in your Sailplay account. The store_department_id and store_department_key identifiers are located in the department card. pin_code can be obtained from the employee's card.
2. Get identifiers through a Sailplay manager. If you do not have access to the account, request the identifiers from your personal Sailplay manager.

❗️ Important

Do not send identifiers, tokens, or other sensitive data in open channels (chats, messengers, task management systems). Any leak can lead to unauthorized access and financial loss.

---

Example cURL request to get a token

curl --request POST \
     --url https://sailplay.net/api/v2/login \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data store_department_id=3354 \
     --data store_department_key=450013 \
     --data pin_code=230945

---

Token update policy

• Standard TTL. The standard token lifecycle setting works with no time limit. However, Sailplay recommends automating token renewal every 24 hours using a background task.
• Changing the TTL. The TTL can be increased or decreased upon request through Sailplay technical support.
• Forced update. If you receive a response with the error "status_code": -7 to any ordinary request, immediately initiate a second call to api/v2/login/ and update the token in all subsequent requests to the system.

An example of a response to a regular request if the token is not valid:

{
	"status": "error",
	"status_code": -7,
	"message": "Authentication token is invalid"
}

An example of a response to a request to get a token if the key parameters are passed correctly:

{
  "status": "ok",
  "token": "db24834db10ed8a58ab8d2ce02be41ab03a86b21"
}

🚧 Recommendations for secure key storage

Keys and tokens should under no circumstances be fixed in the source code. Store them only in environment variables or in specialized secret-stores, following the generally accepted principles set forth in NIST SP 800-57 and OWASP ASVS. If a token is compromised, it can be quickly disabled and re-created along with a new store_department_key and pin_code. To do this, contact Sailplay technical support. Request instructions on how to correctly deactivate the current token and update the key identifiers.