Authentication

To use the different resources offered by the API, it is necessary to authenticate as an integration user. Currently, there are two ways to do this: API Key and authentication form (deprecated).

API Key

The API key authentication system works by generating and exchanging a unique key (API Key) between the client making the request and the API server.

To use this authentication system, simply include an "Authorization" header with the value "Bearer" and the API Key provided by Orquest in each call, as shown in the following example:

curl -X 'GET' \
  'https://importer.orquest.es/api/v2/businesses/businessId/services' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXX'

When a request that includes an API Key is received, the server verifies the validity of the key by querying the database to ensure that the provided key is valid and associated with a user through their userId.

If the API Key is valid and access is authorized, the API responds to the request with the requested data or required action. If the key is not valid or access is not authorized, the API will return the corresponding error message.

This process is repeated for each request, but it does not provide additional information about the user or the application itself, meaning the API Key does not contain shared data about the user, such as their name or email address.

Form

⚠️ Deprecated section

The traditional system uses form-based authentication, with username and password as credentials. By sending an HTTP POST request to the URL login with the correct credentials, a session token (JSESSIONID) is obtained.

It is necessary to send username and password in the body of the request as URL-encoded data, as shown in the following example:

curl -X POST https://importer.orquest.es/login \
-d "username=******&password=******" \
-H "Content-Type: application/x-www-form-urlencoded"

The credentials are validated on the server and a session linked to a unique key (token) is created, which must be included in all HTTP requests and responses exchanged between the client and the server.

  • Successful HTTP response

  • Failed HTTP response

The server returns an HTTP response with code 200 containing an HTTP Set-Cookie header with the name JSESSIONID.

The cookie value is included in the response body to facilitate session management in some client tools with limited capabilities to process HTTP messages.

HTTP/1.1 200
Set-Cookie: JSESSIONID=MDY2MTFjZjktOWE2Yy00NDY5LTlhZjktYjE2NDBkNzZjNzFm; Path=/; HttpOnly; SameSite=Lax
Content-Type: application/json;charset=UTF-8
Content-Length: 65

{"JSESSIONID":"MDY2MTFjZjktOWE2Yy00NDY5LTlhZjktYjE2NDBkNzZjNzFm"}

The server returns an HTTP response with code 401, indicating that the request has not been executed because it lacks valid authentication credentials.

The same response is obtained in the following cases:

  • When an operation is invoked without including the JSESSIONID cookie.

  • When an invalid JSESSIONID cookie is included.

Thus, after a successful authentication, all subsequent requests must include the JSESSIONID cookie with the value provided in the response.

curl --localization --request POST 'http://server/api' --header 'Content-Type: application/json' \
-H 'Cookie: JSESSIONID=0000000000000000000000000'...

For security reasons, it is recommended not to send the username and password in the URL:

https://importer.orquest.es/login?username=api_username&password=12345

Best Practices

Inactivity Periods

In form-based authentication, the session does not have a predefined maximum lifetime, but inactivity periods are controlled. In this sense, after the maximum inactivity time has passed, the session expires and the user will have to repeat the authentication process to receive a new valid JSESSIONID cookie.

Each new request to the API resets the inactivity period.

Session Management

In order to use resources efficiently, users need to manage sessions responsibly. It is therefore advised to use the endpoint logout to ensure that sessions are not left open.

The number of sessions per user is 25.

Session management is not necessary in API Key authentication, as the API Key assigned to the user must be included in each request.

Retry Policy

The API retry policy allows handling situations where a request temporarily fails. Instead of simply returning an error, the retry policy allows the request to be retried after a short period of time, hoping the failure is temporary and the request will succeed on a subsequent attempt. This policy allows:

  • Detecting temporary errors such as network failures, temporary server overload, or latency issues.

  • Defining a retry strategy to determine when and how many times failed requests should be retried.

  • Logging and monitoring to identify persistent issues that may require further investigation.