Copy page

Getting Started

Authentication

All requests to the IntelCenter API must include a valid API key.

Authentication is performed using a Bearer token in the HTTP Authorization header.

---

Header Format

Code
Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with the API key provided by IntelCenter.

---

Example Request

Example request using curl:

Code
curl --request GET \
  --url https://api.intelcenter.com/v1/icdb/videos \
  --header "Authorization: Bearer YOUR_API_KEY"

---

Using Authentication with Query Parameters

Authentication works the same way for all requests, including those with query parameters:

Code
curl --request GET \
  --url "https://api.intelcenter.com/v1/icd/videos?search=isis&entity=ISIS&page=1&per_page=10" \
  --header "Authorization: Bearer YOUR_API_KEY"

---

MCP Authentication

MCP (Model Context Protocol) endpoints use the same authentication method.

When connecting via MCP (e.g., ChatGPT or other AI tools), your API key must be included as a Bearer token in the request headers.

MCP endpoints:

• /mcp-icd
• /mcp-all

Access to MCP tools is automatically restricted based on your API key permissions.

---

Dataset & Feature Access

API keys are scoped to specific datasets and features.

This means:

• Some keys may only access ICD datasets
• Some keys may have restricted access to ICDB entities
• Some keys may not have access to Natural Language or Domain GenAI endpoints

If your API key does not have access to a dataset or feature, the API will return a 403 Forbidden response.

Example:

Code
{
  "error": "FORBIDDEN",
  "message": "You do not have access to this dataset or feature."
}

---

Usage Limits (Rate Limits & Quotas)

API keys are subject to usage controls based on their assigned tier.

These may include:

• Rate limits (requests per minute for search and detail endpoints)
• Domain GenAI limits (per-minute, hourly, and daily limits)
• Daily request quotas
• Monthly request quotas
• Maximum results per request (per_page)

Limits are enforced automatically at the gateway level.

If a limit is exceeded, the API will return a 429 Too Many Requests response.

Example response:

Code
{
  "error": "quota_exceeded",
  "message": "This API key exceeded a usage or rate limit and the request was blocked.",
  "tier": "trial",
  "rate_limit": "domain-genai",
  "limits": {
    "daily_requests": 100,
    "monthly_requests": 1000
  },
  "action": "Wait for your quota to reset or contact IntelCenter if you need a higher usage allowance."
}

---

Error Responses

401 Unauthorized

Returned when authentication fails.

Common causes:

• Missing Authorization header
• Invalid API key
• Revoked API key

Example:

Code
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

---

403 Forbidden

Returned when your API key is valid but does not have permission to access the requested dataset or feature.

Example:

Code
{
  "error": "FORBIDDEN",
  "message": "You do not have access to this dataset or feature."
}

---

Security Best Practices

To protect your API key:

• Do not expose your API key in client-side code (e.g., browsers or mobile apps)
• Store your API key securely (e.g., environment variables or secure vaults)
• Rotate your API key periodically
• Immediately revoke compromised keys
• Use backend proxying when integrating with frontend applications

---

Troubleshooting

If you are receiving authentication or access errors:

1. Verify the Authorization header is present and correctly formatted
2. Confirm your API key is valid and active
3. Ensure there are no extra spaces or characters in the header
4. Check that your key has access to the requested dataset or feature
5. Confirm you have not exceeded rate limits or quotas