Authentication

Overview

Our API uses API Key authentication via HTTP headers. This simple yet secure method allows you to authenticate all requests without managing tokens, refresh flows, or session states.

Key Characteristics

• Static credentials - API keys don't expire unless you set an expiration date
• Header-based - Keys are transmitted via the X-API-Key HTTP header
• Tenant-scoped - Each key is associated with a specific tenant and inherits that tenant's permissions
• Full access - Keys currently provide admin-level access to all endpoints available for your tenant type

---

Making Authenticated Requests

Every API request must include your API key in the request headers.

Header Format

X-API-Key: your_api_key_here

Request Examples

curl

bash

curl -X GET "https://api.equipme.io/v1/organization/employees" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

JavaScript (fetch)

javascript

fetch('https://api.equipme.io/v1/organization/employees', {
  method: 'GET',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

---

Authentication Errors

401 Unauthorized

This status code indicates an authentication problem with your API key.

Common causes:

Error Description	Cause	Solution
"Required authorization header is missing"	No X-API-Key header provided	Add the header to your request
"Invalid API Key."	Key doesn't exist or was typed incorrectly	Verify you copied the key correctly; generate a new one if needed
"Invalid API key. Your API key has expired. Please generate a new key to continue using the API."	Key expiration date has passed	Generate a new API key

Example error response:

json

{
  "errorCode": "AuthenticationFailed",
  "errorDescription": "Invalid API key. Your API key has expired. Please generate a new key to continue using the API."
}

403 Forbidden

This status code means your API key is valid, but you don't have permission to access the requested resource.

Common causes:

• Accessing an endpoint not available for your tenant type (e.g., supplier endpoint as a customer)

Example error response:

json

{
  "errorCode": "AccessDenied",
  "errorDescription": "Attempted to perform an unauthorized operation."
}

404 Not Found

This status code indicates that the requested resource either doesn't exist or is not accessible with your API key.

Security Note: For security reasons, we return 404 in both cases:

• The resource truly doesn't exist
• The resource exists but is outside your tenant's access scope.

This prevents malicious actors from discovering which resources exist in the system by probing different IDs.

Common scenarios:

• Requesting a resource with an invalid or non-existent ID
• Attempting to access another tenant's resources
• Using an outdated ID for a deleted resource

Example error response:

json

{
  "errorCode": "NotFound",
  "errorDescription": "Requested resource was not found."
}

Troubleshooting:

• Verify the resource ID is correct
• Confirm the resource belongs to your tenant
• Check if the resource might have been deleted

---

API Key Lifecycle

Creation

API keys are created through the application interface. See Creating Your API Key for detailed instructions.

Storage

Once created, store your API key securely:

• Use environment variables or secret management systems
• Never commit keys to version control
• Encrypt keys in configuration files
• Limit access to keys on a need-to-know basis

Rotation

While API keys don't expire automatically (unless you set an expiration), regular rotation is a security best practice.

Recommended rotation schedule:

• Production keys: Every 90 days
• Immediate rotation if a key is suspected to be compromised

Rotation process:

1. Generate a new API key with an expiration date
2. Update your integration to use the new key
3. Test the integration thoroughly
4. Delete the old key once confirmed the new one works
5. Update your documentation and secret management systems

Revocation

Delete API keys immediately when:

• An integration is decommissioned
• A key may have been exposed or compromised
• A team member with key access leaves the organization
• You're consolidating multiple keys

To delete a key:

1. Navigate to Settings → Integrations → API-Key (Customers) or Pro → Integrations → API Key (Suppliers)
2. Locate the key in the list (identifiable by last 4 characters)
3. Click the delete/remove button
4. Confirm deletion

Warning: Deleting a key immediately invalidates it. All requests using that key will fail with a 401 error. Ensure you've updated all integrations before deleting.

---

Security Best Practices

Transport Security

• Always use HTTPS - Never transmit API keys over unencrypted HTTP connections
• Verify SSL certificates - Don't disable certificate validation in production code
• Use TLS 1.2 or higher - Ensure your HTTP client supports modern encryption standards

Key Management

Do's ✓

• Store keys in environment variables or dedicated secret managers
• Use different keys for different environments (dev, staging, production)
• Set expiration dates and rotate keys regularly
• Monitor API usage for anomalies
• Implement key rotation procedures before keys expire
• Document which keys are used where

Don'ts ✗

• Hardcode keys in source code
• Expose keys in client-side applications (JavaScript, mobile apps)
• Share keys via email, chat, or other unencrypted channels
• Log API keys in application logs or error messages
• Use the same key across multiple integrations or third parties
• Commit keys to version control (even in private repositories)

Incident Response

If you suspect a key has been compromised:

1. Immediately delete the compromised key in the application interface
2. Generate a new key with a different expiration policy
3. Update all integrations to use the new key
4. Document the incident and lessons learned
5. Notify stakeholders if sensitive data may have been accessed

---

Rate Limiting and Authentication

Rate limits apply per API key. If you have multiple integrations, consider using separate API keys to avoid one integration affecting another's rate limits.

See Rate Limits for details on current limits and handling rate limit errors.

---

FAQ

Can I use multiple API keys simultaneously?

Yes, you can create and use multiple API keys at the same time. This is useful for:

• Separating development and production environments
• Isolating different integrations or services
• Providing keys to third-party integrators while maintaining your own

What happens if I delete a key that's still in use?

The key is immediately invalidated. All subsequent requests using that key will return a 401 Unauthorized error. Make sure to update your integrations before deleting keys.

Can I retrieve a key after creation?

No. For security reasons, API keys are only displayed once during creation. If you lose a key, you must generate a new one and update your integration.

How long does it take for a new key to become active?

New API keys are active immediately after creation. There's no propagation delay.

Can I rename or edit an existing API key?

Currently, you cannot modify an existing key. If you need to change settings, create a new key and delete the old one.