Skip to main content

​
Authentication

This page covers authentication for the direct REST API on https://api.deepface.dev. ChatGPT connects through OAuth; other MCP clients use dedicated MCP keys from the dashboard. Both 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.
  • AI agents that do not already have a configured REST key can open 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 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. Connect ChatGPT with OAuth, or create dedicated MCP keys for other clients at https://www.deepface.dev/mcp.

​
Connect ChatGPT with OAuth

Connect the deepface.dev plugin and sign in to your existing account. Review and approve the consent screen to allow MCP face comparisons, embeddings and your account’s spending-alert tools. Compute uses your allowance and may incur charges under your plan. OAuth does not grant dashboard access or permission to change payment methods, plans, tariffs or spending caps. The registered public client is deepface-chatgpt, with authorization-code flow and S256 PKCE. The resource is https://www.deepface.dev/mcp and the scope is mcp:tools. Access tokens last one hour; refresh tokens rotate and the connection expires after 30 days. Reconnect when prompted. Revoke the ChatGPT OAuth key on the dashboard MCP page to end access immediately. Do not paste tokens into chat. Discovery: https://www.deepface.dev/.well-known/oauth-authorization-server and https://www.deepface.dev/.well-known/oauth-protected-resource/mcp. Other MCP clients can continue using the dedicated keys described below.

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