Authenticating with an API key

The CLEVI gateway authenticates both the OpenAI-compatible path and the Anthropic-compatible path with a single API key.
You configure two values on the client: the authentication header that carries the key, and the base URL for your SDK. The accepted header formats and the base URL differ between the two specifications.
Once configured, you can confirm authentication immediately by listing the models.
The gateway returns 401 when authentication fails, and 403 when a request passes authentication but does not meet permission or quota conditions.

Issue your API key on the API keys page in the console. You can also revoke keys and manage their scope on the same page.

Authentication header

Both specifications carry the API key in a single request header. Use either the X-API-Key header or the Authorization header; the accepted format depends on the specification.

On the OpenAI-compatible path, the Authorization header requires the Bearer prefix. If you send the key without the prefix, the gateway rejects the request.

Header names are case-insensitive, so the x-api-key header sent by the Anthropic SDK works as is. If both headers are present, the X-API-Key value takes precedence.

Base URL

You can keep using your existing SDK by changing only the base URL to the address below. The two addresses differ in whether they include /v1, so set the address for your specification exactly as shown.

Verifying authentication

After setting the key and the base URL, list the models to verify that authentication works. The examples below run the same query with curl, the OpenAI SDK, and the Anthropic SDK. Replace sk-... with the key issued on the API keys page.

With curl, specify the full path up to /v1/models for both specifications. The first command uses the X-API-Key header on the OpenAI-compatible path, and the second uses the Authorization header on the Anthropic-compatible path.

curl https://platform.clevi.net/api/v2/aiservice/openai/v1/models \
  -H "X-API-Key: sk-..."

curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/models \
  -H "Authorization: Bearer sk-..." \
  -H "anthropic-version: 2023-06-01"

For the OpenAI SDK, set base_url to the address that includes /v1.

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)

for model in client.models.list():
    print(model.id)

For the Anthropic SDK, set base_url to the address that ends before /v1.
Authentication uses the x-api-key header that the SDK sends, with no changes.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/anthropic",
)

for model in client.models.list(limit=20).data:
    print(model.id)

In every example, a 200 response means authentication succeeded, and data in the response contains the models this key can call. If you get 401, follow the steps in the next section to find the cause.

Authentication failures

The gateway returns 401 when the key is missing, expired, or revoked. A call without a key on the OpenAI-compatible path returns the body below; on the Anthropic-compatible path, error.type is authentication_error.

{
  "error": {
    "message": "API key is required.",
    "type": "invalid_request_error"
  }
}

If you receive 401, check the following in order.

1. Check the key status on the API keys page. If the key is expired or revoked, issue a new one.
2. Confirm that the header name is X-API-Key or Authorization.
3. If you use the Authorization header on the OpenAI-compatible path, confirm that the Bearer prefix is present.

After making the fix, run the model list query from the Verifying authentication section again and confirm that you get 200.

Additional headers

All of the following headers are optional. We recommend setting X-Request-Id so that you can trace issues.

If 5xx errors keep occurring, report them through Help & Support and include the X-Request-Id. If you set the value yourself, you can match it against your client logs right away.