Skip to main content

​
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://deepface.dev/mcp.

​
Account access

  • Create an account at deepface.dev/signup.
  • AI agents that do not already have a configured REST key can open deepface.dev/signup?agent=1, sign up anonymously, then create their own standard REST API key or dedicated MCP key in the dashboard.
  • Return to 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; it is not part of the public tester flow.
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://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://deepface.dev/mcp.
  • Do not reuse MCP keys for direct REST requests.

​
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.