Authentication

Learn how to authenticate your API requests securely using API keys.

📋 API Access Requirements

To use the Mentibus API, you need:

API Access Plan or Enterprise Plan subscription
An API key generated from your account settings
Valid authentication headers in all requests

API Keys

The Mentibus API uses API keys for authentication. All API requests must include a valid API key in the Authorization header using the Bearer token format.

API Key Format

All Mentibus API keys start with mk_ followed by a secure random string.

Getting Your API Key

1
Sign up or log in to your Mentibus account
2
Navigate to Settings and go to the API Keys section
3
Click "Create API Key" and give it a descriptive name
4
Copy and securely store your API key immediately (it won't be shown again)

Get Your API Key

Using Your API Key

Include your API key in the Authorization header of every request using the Bearer token format:

HTTP Header

Authorization: Bearer your_api_key_here

Example Requests

cURL

curl -X GET "https://mentibus.xyz/api/v1/companies" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

JavaScript (fetch)

const response = await fetch('https://mentibus.xyz/api/v1/companies', {
  headers: {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Python (requests)

import requests

headers = {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json'
}

response = requests.get('https://mentibus.xyz/api/v1/companies', headers=headers)
data = response.json()

API Key Permissions

API keys can have different permission levels that control what operations they can perform:

Read

Access to GET endpoints for retrieving data

• List companies, people, investors

• Get specific entity details

• Search across all entities

Write

Includes Read + POST/PUT endpoints for creating and updating

• Create new entities

• Update existing entities

• All read operations

Delete

Includes Write + DELETE endpoints for removing data

• Delete entities (soft delete)

• All write operations

• All read operations

Rate Limiting

Each API key has rate limits based on your plan. Rate limit information is included in response headers:

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 2024-01-15T11:30:00Z

API Access Plan

1,000

requests/day

30,000

requests/month

Enterprise Plan

Custom

Higher limits available

Security Best Practices

Important Security Guidelines

• Never expose API keys in client-side code or public repositories
• Store API keys securely using environment variables or secret management
• Rotate API keys regularly and revoke unused keys
• Use different API keys for different environments (dev, staging, prod)
• Monitor API key usage and set up alerts for unusual activity

Environment Variables Example

.env

MENTIBUS_API_KEY=your_api_key_here

JavaScript

const apiKey = process.env.MENTIBUS_API_KEY;

const response = await fetch('https://mentibus.xyz/api/v1/companies', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

Authentication Errors

Common authentication error responses:

401 Unauthorized - Missing API Key

{
  "success": false,
  "error": "Missing or invalid authorization header",
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "v1"
  }
}

401 Unauthorized - Invalid API Key

{
  "success": false,
  "error": "Invalid API key",
  "meta": {
    "requestId": "req_def456",
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "v1"
  }
}

403 Forbidden - Insufficient Permissions

{
  "success": false,
  "error": "Insufficient permissions for write operations",
  "meta": {
    "requestId": "req_ghi789",
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "v1"
  }
}

429 Rate Limited

{
  "success": false,
  "error": "Rate limit exceeded",
  "meta": {
    "requestId": "req_jkl012",
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "v1"
  }
}