> For the complete documentation index, see [llms.txt](https://docs.capedatahub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.capedatahub.com/cape-stock-api-documentation.md). # CAPE Stock API Documentation ### Introduction This document serves as a comprehensive guide to utilising the CAPE Stock API. It outlines the required payloads for successful API calls and provides examples of payloads returned in the case of unsuccessful requests. Additionally, it details the API's authorisation process to ensure secure and authenticated calls. ### Security #### **1. Client Authentication (First Request)** **What's Happening?** * A **POST request** is made to the authentication API (/api/ClientAuthentication). * The **client's username and password** are sent as x-www-form-urlencoded data. * If credentials are valid, the server responds with a **token (JWT - JSON Web Token)**. **Security Considerations** * **Authentication process:** The client must prove their identity by providing credentials. * **Token Issuance:** The server generates a signed JWT token upon successful authentication. * **Token Content:** The JWT might contain user details and permissions, encoded and signed (but not encrypted). **URL:** QA Ask Copy ``` https://dev-icon.cloud:9525/api/ClientAuthentication ``` PROD Ask Copy ``` https://prosol.cloud:9525/api/ClientAuthentication ``` **Method:** * ClientAuthentication: Retrieve bearer token. * Action: POST

#### **2. Making API Requests with the Bearer Token** **What's Happening?** * The **Bearer Token** received from authentication is used in the **Authorisation** header of the API request. * A **POST request** is made to another API (/api/CAPEStockAPI) with JSON body parameters. * The server verifies the **validity of the token** before allowing access. * If valid, the server returns a **200 OK** response with the requested data. **Security Considerations** * **Authorisation:** Only authenticated users with a valid token can access protected endpoints. * **Token Expiry:** JWTs typically have an expiration time, after which they must be refreshed. * **Token Storage:** Storing tokens securely (e.g., in an encrypted store) is crucial to prevent leaks. * **Replay Attacks:** If an attacker gets the token, they can make requests unless mitigations like token expiration or refresh tokens are in place.

#### **3. API Response Validation** **What's Happening?** * The response from the CAPEStockAPI confirms that the request was authorised. * The API returns structured **JSON data** about vehicle stock details. * The token ensures that only authorised users retrieve this information. **Security Best Practices** * **Use HTTPS:** Always send tokens over an encrypted connection. * **Implement Token Expiry & Refresh Mechanism:** Prevent long-lived access. * **Restrict Token Scope:** Assign permissions based on user roles. * **Monitor and Revoke Tokens if Compromised.** ### Endpoints #### Get Dealer Vehicle Stock information **Description:** This endpoint will be used for all Stock vehicle information retrieval operations, and in this case, in order to retrieve vehicle information for each dealer using a unique identifier, dealer code and vehicle status. **URL:** QA Ask Copy ``` https://dev-icon.cloud:9528/api/CAPEStockAPI ``` PROD Ask Copy ``` https://prosol.cloud:9528/api/CAPEStockAPI ``` **Method:** * CAPEStockAPI: Get vehicle stock Information regarding a specific dealer from CAPE. * Action: POST --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.capedatahub.com/cape-stock-api-documentation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.