> For the complete documentation index, see [llms.txt](https://hub.equipme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.equipme.io/development/getting-started.md). # Getting Started ### Prerequisites Before you begin integrating with our API, ensure you have the following: * **Active tenant account** - You need either a Customer or Provider account on our platform * **Basic REST API knowledge** - Familiarity with HTTP methods, headers, and JSON * **API testing tool** - Such as Postman, Insomnia, curl, or your preferred HTTP client * **Secure credential storage** - A safe place to store your API key (environment variables, secret manager, etc.) *** ### Understanding Your Access Level Our platform serves two types of tenants: **Customers** and Provider**s**. Both have access to the API, though they access the API key management through different menu locations in the application. If you don't have an account yet, you can register a new tenant. For further details how to register see: * [Customer Registration](/classes/portal-quick-setup/portal-registration.md) * Provider Registration #### Current Permissions Model API keys currently provide **full administrative access** to all documented API endpoints. This means any integration using an API key can perform all available operations within your tenant's scope. #### Access by Tenant Type The API is organized into **Customer endpoints** and P**rovider endpoints**, clearly marked in our API Reference documentation. * **Customer tenants** have access to customer-specific endpoints * **Provider tenants** have access to provider-specific endpoints * **Providers who also use the platform as customers** (self-supply scenario) can access both provider and customer endpoints You'll find the API key management interface at different locations depending on your tenant type: * **Customers:** Settings → Integrations → API-Key * **Providers:** Equipme Pro → Integrations → API Key Refer to the API Reference to see which endpoints are available for your tenant type. *** ### Creating Your API Key #### Navigating to API Key Management The location depends on your tenant type: **For Customers** Navigate to: **Settings → Integrations → API-Key** **For Providers** Navigate to: **Pro → Integrations → API Key** #### Generating a New API Key Once you're on the API Key management page: 1. **Select an expiration date** (optional) * Default: Unlimited (no expiration) * Recommended: Set an expiration date for production keys and rotate them regularly 2. **Click "Add"** to generate the key 3. **Copy and store your API key immediately** {% hint style="info" %} **Important:** The API key will only be displayed once during creation. After you close this dialog, you won't be able to retrieve the full key again. Store it securely immediately. {% endhint %} 4. The system automatically creates a generic username (e.g., "") to track actions performed via this key
#### Managing Your API Keys On the API Key management page, you can: * **View all active keys** - Only the last 4 characters are displayed for security * **Identify keys** - Each key shows its expiration (if set) * **Delete keys** - Remove keys that are no longer needed * **Create multiple keys** - You can have several active keys simultaneously (useful for different integrations or environments) #### Key Expiration When an API key expires: * All requests using that key will return a `401 Unauthorized` status * The error message will indicate that the key has expired * You'll need to generate a new key and update your integration {% hint style="info" %} There is currently no automatic notification before a key expires. We recommend setting calendar reminders if you use keys with expiration dates. {% endhint %} *** ### Your First API Call Now that you have your API key, let's verify it works by making a test request. #### Testing Your Connection You can use the health endpoint to verify your API key and connectivity. **Endpoint:** `GET /health`\ **Purpose:** Verify API connectivity and authentication #### Example: Using curl bash ```bash curl -i GET "https://api.equipme.io/health" \ -H "X-API-Key: your_api_key_here" \ -H "Accept: application/json" ``` #### Expected Response A successful request returns a `204 No Content` status with an empty response body indicating the API is healthy. #### Troubleshooting Your First Request If your request fails, check the following:
Status CodePossible IssueSolution
401Invalid or expired API keyVerify you copied the entire key correctly; generate a new key if expired
403No access to this endpointCheck if you are using the correct http method and if the endpoint name is correct
429Too many requestsWait a moment and try again; see Rate Limits
5xxServer errorCheck our Status Page or contact support
*** ### Security Best Practices Protecting your API key is critical for maintaining the security of your integration. #### Do's ✓ * **Store keys securely** - Use environment variables, secret managers, or encrypted configuration files * **Use separate keys** - Create different keys for development, staging, and production environments * **Set expiration dates** - For production keys, use expiration dates and establish a rotation schedule * **Delete unused keys** - Remove keys immediately when they're no longer needed * **Limit key distribution** - Only share keys with team members who absolutely need them * **Use HTTPS only** - Always connect to the API over encrypted connections #### Don'ts ✗ * **Never commit to version control** - Don't include API keys in your Git repositories, even private ones * **Never expose in client-side code** - Don't embed keys in frontend JavaScript, mobile apps, or any publicly accessible code * **Never share via unsecured channels** - Don't send keys through email, Slack, or other unencrypted communication * **Never reuse across integrations** - Don't use the same key for multiple projects or third-party integrations * **Never log keys** - Ensure your application doesn't write keys to log files or error tracking systems *** ### What's Next? Now that you're authenticated and have made your first successful API call, you're ready to start building your integration. #### Recommended Next Steps 1. **Authentication** - Learn more about authentication requirements and best practices 2. **Core Concepts** - Understand HATEOAS principles, pagination, and response structures 3. **Working with the API** - Discover common patterns for polling, filtering, and data synchronization 4. **API Reference** - Browse all available endpoints for your tenant type 5. **Error Handling** - Learn how to handle errors gracefully in your integration #### Common Use Cases (TODO) Explore these guides to see practical examples: * **Synchronizing Orders** - Keep your systems in sync with order updates * **Synchronizing Service Portfolio** - Create and maintain your service offering --- # 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: ``` GET https://hub.equipme.io/development/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.