==============
Authentication
==============

CorePlexML supports two authentication mechanisms. For programmatic access
(API calls, SDK, CI/CD pipelines), use **Bearer tokens (API keys)**.

API Key Authentication
----------------------

Generate an API key from the web UI under **Settings > API Keys**, or
programmatically via the auth API.

Include the key in every request as a ``Bearer`` token:

.. code-block:: text

   Authorization: Bearer cpx_live.abc123def456...

**curl example:**

.. code-block:: bash

   export BASE_URL="https://your-domain.com"
   export API_KEY="cpx_live.abc123def456"

   curl "$BASE_URL/api/projects" \
     -H "Authorization: Bearer $API_KEY"

**Python ``requests`` example:**

.. code-block:: python

   import requests

   BASE_URL = "https://your-domain.com"
   headers = {"Authorization": "Bearer cpx_live.abc123def456"}

   resp = requests.get(f"{BASE_URL}/api/projects", headers=headers)
   projects = resp.json()

**SDK example:**

.. code-block:: python

   from coreplexml import CorePlexMLClient

   client = CorePlexMLClient(
       base_url="https://your-domain.com",
       api_key="cpx_live.abc123def456",
   )
   projects = client.projects.list()

Creating an API Key Programmatically
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

First authenticate with email/password to get a session, then create a key:

.. code-block:: bash

   # Login to get session cookie
   curl -X POST "$BASE_URL/api/auth/login" \
     -H "Content-Type: application/json" \
     -c cookies.txt \
     -d '{"email": "you@example.com", "password": "your-password"}'

   # Create API key
   curl -X POST "$BASE_URL/api/auth/api-keys" \
     -b cookies.txt \
     -H "Content-Type: application/json" \
     -d '{"name": "CI Pipeline", "scopes": ["read", "write", "predict"]}'

The response contains the full key -- store it securely. The key is shown
only once.

API Key Scopes
^^^^^^^^^^^^^^

Each key carries one or more scopes that restrict its permissions:

.. list-table::
   :header-rows: 1
   :widths: 15 85

   * - Scope
     - Permissions
   * - ``read``
     - List and view all resources (projects, datasets, models, etc.)
   * - ``write``
     - Create, update, and delete resources
   * - ``predict``
     - Make predictions via models and deployments
   * - ``admin``
     - Manage users, settings, and other API keys

A key with scopes ``["read", "predict"]`` can list models and make
predictions but cannot create projects or delete datasets.

Session Authentication
----------------------

Session-based authentication is used by the web UI. After calling
``POST /api/auth/login`` with email and password, the server sets an
``HttpOnly`` cookie that is sent automatically on subsequent requests.

This method is useful for browser-based integrations or testing with
tools like Postman:

.. code-block:: python

   session = requests.Session()
   session.post(f"{BASE_URL}/api/auth/login", json={
       "email": "you@example.com",
       "password": "your-password",
   })
   # session now carries the cookie
   resp = session.get(f"{BASE_URL}/api/projects")

Error Responses
---------------

Authentication failures return one of:

- **401 Unauthorized** -- Missing or invalid API key / session.
- **403 Forbidden** -- Valid credentials but insufficient scopes.
- **429 Too Many Requests** -- Rate-limited (login and password endpoints).

.. code-block:: json

   {
     "detail": "Invalid or expired API key"
   }

.. seealso::

   - :doc:`/api-reference/authentication` -- Full authentication API reference.
   - :doc:`/api-reference/errors` -- Complete error code reference.