# Authenticate API requests

Source: https://cicora.ai/en/docs/authentication

## Create and save a key

Open [API keys in the cabinet](https://app.cicora.ai/api-keys), check that the correct workspace is active, and create a key named after the server or project that will use it. The complete key is shown once. Later, the cabinet shows only its name and masked prefix, which is safe to use when identifying the key to support.

Save the complete key immediately in a server environment variable or secret manager:

```bash
export CICORA_API_KEY="sk_..."
```

**Keep the key out of browsers**


Never put a platform key in frontend source, a public browser bundle, a repository, screenshots, or support messages. Browser code should call your authenticated backend; that backend calls cicora.ai.


*A platform key is attached to a request before it reaches the API.*

*Bearer authentication for public API formats.*

## Send the key as Bearer authorization

The API reads the key from the `Authorization` header. Verify it with model discovery before configuring an SDK or coding tool:

```bash
curl --fail-with-body --silent --show-error https://api.cicora.ai/v1/models \
  -H "Authorization: Bearer $CICORA_API_KEY"
```

A successful response has `object: "list"` and a `data` array. Choose an available model and copy its exact `id`; do not keep a model list copied from an old guide. The catalog can also explain that a model is unavailable to the active workspace.

## Separate projects and rotate safely

Use a separate key for each project or server. This makes its usage, spend limits, and revocation independent.

If a key is lost, exposed, or no longer needed, revoke it in the cabinet. For rotation without downtime, create a replacement, update the server secret, repeat `GET /v1/models` with the replacement, and only then revoke the old key. A revoked key cannot be restored.

## Prepare safe diagnostics

A **public error code** is the client-facing value such as `error.code` in an API error response. Record that code, the HTTP status, endpoint, model ID, approximate time with timezone, and the masked key prefix. Never include the complete key or sensitive request content.

## Troubleshooting


**The API returns 401 or says the key is invalid**


Check that the header starts with `Bearer `, that the running process received `CICORA_API_KEY`, and that the key belongs to the active workspace and has not been revoked. Test the same environment with `GET /v1/models` without printing the secret.


**The complete key is no longer visible in the cabinet**


This is expected after the one-time display. Revoke the lost key, create a replacement, save it server-side, verify it, and then update the application.


**A key appeared in browser code, a repository, or a screenshot**


Treat it as exposed. Revoke it, create a new key, remove the old value from deployed configuration and published material, and move API calls behind your backend.


**Authentication works but the intended model is unavailable**


Read the current entry returned by `GET /v1/models` and its availability reason. Confirm the active workspace, choose an available model, or complete the action indicated by the catalog.

## FAQ

### What is cicora.ai?

cicora.ai is a multi-model AI workspace and compatible API for chat, text, images, video, coding tools, and teams. Start with the [overview](/en.md), [documentation](/en/docs.md), or [model catalog](/en/models.md).

### How is usage billed?

Confirmed usage is charged in USD from the active workspace's prepaid balance. Use the live catalog for current model prices and the [usage guide](/en/docs/usage-costs.md) for settlement details.

### Which protocols and integrations are available?

Documentation covers OpenAI-compatible Chat Completions and Responses, Anthropic Messages, image interfaces, Claude Code, OpenCode, and Codex CLI. Compatibility does not imply support for every upstream parameter.

### Which sources are authoritative and current?

For model IDs, availability, capabilities, limits, and prices, use the [live catalog](/en/models.md). For API behavior, use the matching [documentation page](/en/docs.md). Never include API keys, private workspace data, or preview URLs in public documents.