Authorization in the Connected Courier Service

Integrating the Gold Apple IS with external systems — in this case, the courier service's IS — requires compliance with predefined security parameters. Authorization is performed using a login and password issued by the courier service's technical specialists. The service uses the username and password to generate an access token, which it returns in the response body. Use this token to authenticate subsequent requests. The token's lifetime is set by the courier service IS and is not regulated by the Gold Apple IS. When implementing the authorization mechanism in the courier service IS, it is necessary to independently determine the minimum token lifetime required to process integration requests reliably. The received token must be passed with every request to protected endpoints in accordance with the Bearer Token authentication scheme, in the HTTP Authorization header, in the following format:

info

Authorization: Bearer <access_token>

URL Requirements

The endpoint must be published over the secure HTTPS protocol. The endpoint URL must conform to the following path structure: /api/v1/auth/login.

Any domain name belonging to the courier service's IS may be used. The full URL is formed by the courier service's IS and must have the following format: https://<domain>/api/v1/auth/login

Token Requirements

Cryptographic function — SHA256. Password parameters:

• uppercase and lowercase letters
• digits
• special characters
• > 12 characters

A JWT token is generated based on the login/password pair. This is the so-called access token. Parameters:

• lifetime — set by the courier service IS (minimum acceptable period);
• signing:
  • secret key – a cryptographically strong key (a set of characters, 32+ in length);
  • algorithm — SHA256;
• issuer — <courier service name>
• audience (consumer) — goldapple
• validation:
  • lifetime
  • signature
  • the Issuer and Audience fields

Basic Information

Request method type	POST
Path / URL	/api/v1/auth/login
Description	Method for authenticating the Gold Apple Unified API in the courier service's IS
Direction	The request is executed by the Gold Apple IS. The response is provided by the courier service.

Request

Required Headers

Parameter	Data type	Required	Description	Comment
Host	string	1	Gold Apple Unified API host	Filled in as "subdomain.domain.zone"
Content-Type	string	1	Request content type	Filled in as "application/json"

Payload

Parameter	Data type	Required	Description
username	string	1	Username (login) issued by the courier service
password	string	1	Password for authentication, issued by the courier service

Request example

{
    "username": "Goldapple_UAPI",
    "password": "*************"
}

Response

Response Codes and Messages

Code	Status	Message	Reason
200	OK	Success response	Everything completed successfully
400	Bad Request	Missing or inappropriate required parameters	Required parameters are missing or invalid. The response body must list the names of the fields that failed validation, in an arbitrary string format.
500	Internal Server Error	Server unavailable	The server is unavailable

Successful Response Parameters

Parameter	Data type	Required	Description
access_token	string	1	Access token issued per login/password pair.
expires_in	string	1	Token lifetime, specified in seconds.

Successful response example

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expires_in": "2592000"
}

Unsuccessful Response Parameters

Parameter	Data type	Required	Description
error	string	1	Human-readable description of the error

Unsuccessful response example

{
    "error": "Missing or inappropriate required parameters"
}