Authentication

All Cosmos API requests are authenticated using an API key passed in the request header.

API Key

Include your key in every request via the X-Ingest-Webhook-Secret header:

X-Ingest-Webhook-Secret: your-api-key-here

Obtaining credentials

API keys are provisioned during onboarding by your Cosmos account manager. Each integration partner receives a dedicated key tied to their organization.

Key management

Keys are scoped to a single organization

Do not share keys across environments (staging vs. production)

Keys do not expire automatically, but Cosmos reserves the right to rotate keys with advance notice

WARNING

If you suspect a key has been compromised, contact support@usecosmos.com immediately for rotation.

Troubleshooting

I'm getting a 401 Unauthorized error

Verify that:

The header name is exactly X-Ingest-Webhook-Secret (case-sensitive)

The key value has no trailing whitespace or newline characters

You are using the correct key for the target environment (staging vs. production)

The key hasn't been rotated — check with your Cosmos account manager

The API returns the following error body:

{
  "errors": [
    {
      "code": "not_authorized",
      "detail": null,
      "source": null
    }
  ]
}

API Key#

Obtaining credentials#

Key management#

Troubleshooting#

API Key

Obtaining credentials

Key management

Troubleshooting