Skip to main content

​
Authentication

All API requests require a Bearer token in the Authorization header. You authenticate using an API key that starts with faces_. 
curl https://faces.app/api/v1/projects \
  -H "Authorization: Bearer faces_abc123..."

​
Creating an API key

  1. Sign in to faces.app
  2. Open Settings from the left sidebar
  3. Click Developers
  4. Enter a name for your key (e.g. “My Script”) and click Create key
  5. Copy the key immediately. It’s only shown once.
API keys are shown once at creation. If you lose it, revoke it and create a new one.

​
Option 2: Using the CLI

The CLI handles authentication automatically: 
faces login
This opens your browser, signs you in, creates a key named “CLI”, and saves it to ~/.config/faces/credentials.json.

​
Using the key

Include the key as a Bearer token in every request: 
# With curl
curl https://faces.app/api/v1/projects \
  -H "Authorization: Bearer faces_your_key_here"

# With the CLI (auto-detected from credentials file)
faces list

# Or pass explicitly
faces list --api-key faces_your_key_here

​
Revoking keys

You can revoke keys from Settings > Developers in the dashboard. Revoking a key immediately and permanently invalidates it. Any integrations using that key will stop working.

​
Security best practices

  • Never commit API keys to version control
  • Use environment variables to store keys: 
    export FACES_API_KEY="faces_your_key_here"
  • Create separate keys for each integration so you can revoke them independently
  • Rotate keys periodically by creating a new one and revoking the old one