> 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/authentication.md).

# 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

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

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

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

```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.

{% hint style="info" %}
**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.
{% endhint %}

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

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

{% hint style="warning" %}
**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.
{% endhint %}

***

### 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.


---

# 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/authentication.md?ask=<question>
```

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.