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

All API and MCP requests require authentication. Every request must include
a valid API key so that ApiCrate can identify your account and track usage.


API Keys
--------

API keys are issued through your dashboard at
`apicrate.io <https://apicrate.io>`_. Each key is prefixed with ``ac_usr_``
so it is easy to identify in configuration files and logs:

.. code-block:: text

   ac_usr_k7G2xM9pQ4wL1nR8vT5yB3jF6hD0cA

You can create multiple keys per account and revoke them individually from
the dashboard. Treat your keys like passwords --- store them in environment
variables or secret managers, never in source code.


Using Your Key
--------------

REST API
^^^^^^^^

For REST API requests, pass your key in the ``X-API-Key`` HTTP header:

.. code-block:: bash

   curl -H "X-API-Key: ac_usr_your_key_here" \
        https://api.apicrate.io/api/v1/countries/DE

Alternatively, you can use a JWT token in the ``Authorization`` header:

.. code-block:: bash

   curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
        https://api.apicrate.io/api/v1/countries/DE

MCP Server
^^^^^^^^^^

For MCP clients, the ``X-API-Key`` header is configured once in your client
settings and sent automatically with every tool call. See :doc:`mcp/index`
for client-specific setup instructions.


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

When authentication fails, the server returns an error before any business
logic runs:

.. list-table::
   :widths: 15 30 55
   :header-rows: 1

   * - Status
     - Cause
     - Description
   * - ``401``
     - Missing API key
     - The ``X-API-Key`` header was not included in the request. Verify
       your client configuration includes the header.
   * - ``401``
     - Invalid API key
     - The key does not match any active key in the system. Check for
       typos or regenerate the key from your dashboard.
   * - ``401``
     - Expired API key
     - The key has been revoked or has passed its expiration date. Issue
       a new key from the dashboard.

See :doc:`errors` for the full error reference covering both REST API and
MCP error formats.