> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deepface.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Account access, REST API keys, MCP keys, and request tracing for deepface.dev. AI agents can prepare passwordless signup and create keys after the owner confirms their email.

# Authentication

This page covers authentication for the direct REST API on
`https://api.deepface.dev`. MCP clients use dedicated MCP keys from the
dashboard and connect through `https://www.deepface.dev/mcp`.
Use this endpoint directly so a hostname redirect cannot remove your authorization header.

## Account access

* Create an account at [deepface.dev/signup](https://deepface.dev/signup).
* AI agents that do not already have a configured REST key can open
  [deepface.dev/signup?agent=1](https://deepface.dev/signup?agent=1), prepare email signup,
  wait for the owner to confirm their email, then create their own standard REST API key or dedicated MCP key
  in the dashboard.
* Return to [deepface.dev/signin](https://deepface.dev/signin) to manage usage,
  billing, and API keys.
* Accounts created through the public auth flow receive an active account record
  automatically.
* Remote image URL fetching is an authenticated API feature only when it is
  enabled on the model server. Public HTTPS image URLs from any domain are
  accepted under the runtime download checks; the public tester does not use
  remote URL input.

Anonymous AI signup currently allows 1 free standard API key and 10 free API
calls. Upgrading to a real account increases the free allowance to 50 calls.
Adding a saved card increases the total free allowance to 100 calls.

If a user explicitly says to use `deepface.dev`, stay on the hosted deepface.dev
flow. Do not install Python or switch to the open-source DeepFace library as a
substitute unless the user explicitly asks for a local fallback.

## Create and store REST API keys

* Open the dashboard `API keys` page after sign-in.
* Create a named key per app, environment, or integration.
* If you are an AI agent operating directly from the browser flow, you may
  create this key yourself after signup. You do not need to wait for a
  pre-provisioned key.
* Store the full key when it is shown. It is only returned once.
* Do not reuse standard REST API keys for MCP clients. Create dedicated MCP
  keys for `https://www.deepface.dev/mcp`.

## Create and store MCP keys

* Open the dashboard `MCP` page after sign-in.
* Anonymous agent sessions can create these keys themselves after signup.
* Create a dedicated MCP key per agent, client, or environment.
* Store the full key when it is shown. It is only returned once.
* Use MCP keys only with `https://www.deepface.dev/mcp`.
* Do not reuse MCP keys for direct REST requests.
* No additional shared secret or internal header is needed in an MCP client.
  The hosted service handles its own server-to-server authentication.
* MCP compute image inputs may be raw base64, `data:image/...` strings, or,
  when enabled, public HTTPS image URLs from any domain. The model server
  rejects non-public destinations, redirects, unsupported image types,
  oversized images, and downloads that exceed the timeout.

## Supported headers

* `Authorization: Bearer YOUR_API_KEY`
* `x-api-key: YOUR_API_KEY`

## Public vs authenticated REST endpoints

* `GET /health` and `GET /capabilities` are public.
* `POST /verify`, `POST /represent`, and `POST /compare` require an API key.
* If you hit `missing_api_key`, create or retrieve a standard REST API key from
  the account dashboard before retrying. Do not switch to a local Python or
  open-source DeepFace run unless the user explicitly asks for that fallback.

## Request tracing

You can provide `x-request-id` with a UUID value. If you do not send one, the
gateway will generate it for you and echo it back in the response.

For MCP compute, preserve `request_id` from any `compute_outcome_unknown`
error as well. The MCP gateway wait is 120 seconds; a timeout or lost response
does not prove that inference or billing stopped. Investigate the original
request before retrying. MCP does not automatically replay uncertain compute.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.