docs: change security description within API docs (#1729)

merge apiKey & htttpBearer to one per
make sure all endpoints refer to correct security
adjust descriptions
add admonitions

Author: TC-MO

apify-api/openapi/components/securitySchemes/apiKey.yaml

@@ -1,4 +1,20 @@
 type: apiKey
 name: token
 in: query
-description: API authentication token.
+description: |-
+  API token provided as a query parameter (e.g., `?token=your_token`—less secure).
+  
+  Use your API token to authenticate requests. You can find it on the [Integrations page](https://console.apify.com/account#/integrations) in Apify Console.
+  
+  :::danger Security
+  
+  Do not share your API token (or account password) with untrusted parties.
+  
+  :::
+  
+  _When is authentication required?_
+  - _Required_ for private Actors, tasks, or resources (e.g., builds of private Actors).
+  - _Required_ when using named formats for IDs (e.g., `username~store-name` for stores or `username~queue-name` for queues).
+  - _Optional_ for public Actors or resources (e.g., builds of public Actors can be queried without a token).
+  
+  For more information, see our [integrations documentation](https://docs.apify.com/platform/integrations).

apify-api/openapi/components/securitySchemes/apiKeyActorBuilds.yaml

@@ -1,3 +1,19 @@
 type: http
 scheme: bearer
-description: API authentication token.
+description: |-
+  Bearer token provided in the `Authorization` header (e.g., `Authorization: Bearer your_token`—recommended). [More info](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization).
+  
+  Use your API token to authenticate requests. You can find it on the [Integrations page](https://console.apify.com/account#/integrations) in Apify Console. This method is more secure than query parameters, as headers are not logged in browser history or server logs.
+  
+  :::danger Security
+  
+  Do not share your API token (or account password) with untrusted parties.
+  
+  :::
+
+  _When is authentication required?_
+  - _Required_ for private Actors, tasks, or resources (e.g., builds of private Actors).
+  - _Required_ when using named formats for IDs (e.g., `username~store-name` for stores or `username~queue-name` for queues).
+  - _Optional_ for public Actors or resources (e.g., builds of public Actors can be queried without a token).
+  
+  For more information, see our [integrations documentation](https://docs.apify.com/platform/integrations).

apify-api/openapi/components/securitySchemes/apiKeyQueueId.yaml

@@ -14,25 +14,22 @@ info:
     [JSON](http://www.json.org/) format with UTF-8 encoding,
     with a few exceptions that are explicitly described in the reference.
 
-    To access the API using [Node.js](https://nodejs.org/en/), we recommend the
-    [`apify-client`](https://docs.apify.com/api/client/js) [NPM
+    - To access the API using [Node.js](https://nodejs.org/en/), we recommend the [`apify-client`](https://docs.apify.com/api/client/js) [NPM
     package](https://www.npmjs.com/package/apify-client).
-
-    To access the API using [Python](https://www.python.org/), we recommend the
-    [`apify-client`](https://docs.apify.com/api/client/python) [PyPI
+    - To access the API using [Python](https://www.python.org/), we recommend the [`apify-client`](https://docs.apify.com/api/client/python) [PyPI
     package](https://pypi.org/project/apify-client/).
+
     The clients' functions correspond to the API endpoints and have the same
     parameters. This simplifies development of apps that depend on the Apify
     platform.
 
-    **Note:** All requests with JSON payloads need to specify the `Content-Type:
-    application/json` HTTP header!
-    All API endpoints support the `method` query parameter that can override the
-    HTTP method.
-    For example, if you want to call a POST endpoint using a GET request, simply
-    add the query parameter `method=POST` to the URL and send the GET request.
-    This feature is especially useful if you want to call Apify API endpoints
-    from services that can only send GET requests.
+    :::note Important Request Details
+
+    - `Content-Type` header: For requests with a JSON body, you must include the `Content-Type: application/json` header.
+
+    - Method override: You can override the HTTP method using the `method` query parameter. This is useful for clients that can only send `GET` requests. For example, to call a `POST` endpoint, append `?method=POST` to the URL of your `GET` request.
+
+    :::
 
     ## Authentication
     <span id="/introduction/authentication"></span>
@@ -627,20 +624,8 @@ components:
   securitySchemes:
     httpBearer:
       $ref: components/securitySchemes/httpBearer.yaml
-    httpBearerActorBuilds:
-      $ref: components/securitySchemes/httpBearerActorBuilds.yaml
-    httpBearerStoreId:
-      $ref: components/securitySchemes/httpBearerStoreId.yaml
-    httpBearerQueueId:
-      $ref: components/securitySchemes/httpBearerQueueId.yaml
     apiKey:
       $ref: components/securitySchemes/apiKey.yaml
-    apiKeyActorBuilds:
-      $ref: components/securitySchemes/apiKeyActorBuilds.yaml
-    apiKeyStoreId:
-      $ref: components/securitySchemes/apiKeyStoreId.yaml
-    apiKeyQueueId:
-      $ref: components/securitySchemes/apiKeyQueueId.yaml
 security:
   - httpBearer: []
   - apiKey: []

apify-api/openapi/components/securitySchemes/apiKeyStoreId.yaml

@@ -13,9 +13,7 @@ get:
     This endpoint does not require the authentication token. Instead, calls are authenticated using a hard-to-guess ID of the build. However,
     if you access the endpoint without the token, certain attributes, such as `usageUsd` and `usageTotalUsd`, will be hidden.
   operationId: actorBuild_get
-  security:
-    - apiKeyActorBuilds: []
-    - httpBearerActorBuilds: []
+  security: []
   parameters:
     - name: buildId
       in: path