Authentication
How it works
Every request carries your API key in a CL-API-Key header. The key identifies your
organization, and the API returns only that organization’s data. There’s no session and no
login round-trip — the key travels with each call, so a request is only ever as authorized
as the key you send.
curl https://api.competlab.com/v1/projects \
-H "CL-API-Key: YOUR_COMPETLAB_API_KEY"Create an API key
Keys are managed in the CompetLab dashboard under Settings → API Keys. You’ll need the Owner or Admin role, and each organization can hold up to five active keys.
When you create a key, copy it immediately — the full key is shown once and can’t be retrieved later (only a short hint is stored for display). If you lose it, revoke it and create a new one.
Key format
A key is the prefix cl_live_ followed by 32 hexadecimal characters — 40 characters
total:
cl_live_0123456789abcdef0123456789abcdefThe API validates this shape before anything else, so a malformed key is rejected
immediately with a 401.
Scopes
Keys can be created with a read or read_write scope.
Today scope is not enforced on any endpoint — every valid key has the same access. (The
resource endpoints are read-only GETs; the only POSTs are the stateless free scan tools, which
don’t modify your data.) Treat scope as a label for now, not an access boundary. If enforcement
ships, it’ll be called out here.
Errors
Authentication failures return 401 with the standard { error } envelope:
code | Meaning |
|---|---|
api_key_missing | No CL-API-Key header on the request. |
api_key_invalid | The key is malformed or not recognized — the wrong shape (cl_live_ + 32 hex = 40 characters), or a well-formed key that doesn’t match an active key. |
api_key_revoked | The key was revoked in the dashboard. |
api_key_expired | The key has passed its expiry. |
{ "error": { "code": "api_key_invalid", "message": "Invalid API key", "status": 401 } }Keep your key safe
- Treat a key like a password: don’t commit it, don’t paste it into shared chats, and rotate it if it leaks.
- Store it in a secret manager or an environment variable, not in source.
- Revoke unused keys — you get five active per organization, so retire the ones you don’t need.
Building for an AI agent instead of your own backend? The MCP server uses
the same key and additionally accepts it as a ?api_key= URL parameter for clients that
can’t send custom headers. For the REST API, always use the CL-API-Key header.
FAQ
Where do I get a CompetLab API key?
In the CompetLab dashboard under Settings → API Keys. You need the Owner or Admin role, and each organization can hold up to five active keys. The full key is shown once when you create it — copy it then, because only a short hint is stored afterward. If you lose a key, revoke it and create a new one.
What does a valid key look like?
It's the prefix cl_live_ followed by 32 hexadecimal characters — 40 characters in total. The API validates the shape first, so a key of the wrong length or prefix is rejected immediately; a well-formed key that isn't recognized (a typo, or a key rotated at the source) also comes back as 401 api_key_invalid. All of this happens before the request reaches your data.
Do the read and read_write scopes limit what a key can do?
Not today. Keys can be created with a read or read_write scope, but scope is not enforced on any endpoint — every valid key has the same access. The scope is stored on the key but doesn't gate requests yet. If that changes, it will be documented here.
How do I authenticate the MCP server?
With the same CompetLab API key. The MCP server accepts it as a CL-API-Key header or, for clients that can't send custom headers like Claude on the web, as a ?api_key= URL parameter. The REST API itself uses the header only. See the MCP Connect guide for per-client setup.