Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 Providers. 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:

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 Provider 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

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.

  1. The system automatically creates a generic username (e.g., "apiuser-edf13865-d392-475f-a9d4-f61e577e1935@yourdomain.com") 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

There is currently no automatic notification before a key expires. We recommend setting calendar reminders if you use keys with expiration dates.

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

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 Code
Possible Issue
Solution

401

Invalid or expired API key

Verify you copied the entire key correctly; generate a new key if expired

403

No access to this endpoint

Check if you are using the correct http method and if the endpoint name is correct

429

Too many requests

Wait a moment and try again; see Rate Limits

5xx

Server error

Check 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

Last updated

Was this helpful?