Start

Authentication

The FaceSign API uses API keys to authenticate requests. You can view and manage your API keys in the FaceSign Dashboard.

API Keys

FaceSign provides two types of API keys:

  • Test mode keys - Start with sk_test_ and can be used for development and testing
  • Production mode keys - Start with sk_live_ and should be used in your production environment

Test mode keys have the same capabilities as production keys but will not charge your account. All sessions created in test mode are clearly marked.

Getting your API keys

  1. Log in to your FaceSign Dashboard
  2. Navigate to Settings → API Keys
  3. Copy your API key for the appropriate environment

Keep your API keys secure! Never commit them to version control or expose them in client-side code.

Using API keys

Include your API key in the Authorization header of every request:

curl https://api.facesign.ai/v1/sessions \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

We strongly recommend using environment variables to store your API keys:

FACESIGN_API_KEY=sk_test_4eC39HqLyjWDarjtT1zdp7dc

Client-side authentication

For client-side integrations, use session-specific client secrets instead of your API key:

Client-side

// Never use your API key on the client side!
// Use the client_secret from a session instead
const clientSecret = 'vs_1a2b3c4d5e6f_secret_abc123';

// Initialize the client-side SDK
const facesignClient = new FaceSignClient({
  clientSecret: clientSecret,
});

Rate limiting

API requests are rate limited to ensure fair usage:

  • Test mode: 100 requests per minute
  • Production mode: 1000 requests per minute

If you exceed the rate limit, you'll receive a 429 Too Many Requests response:

Rate limit error

{
  "error": {
    "type": "rate_limit_error",
    "message": "Too many requests. Please retry after 60 seconds."
  }
}

API versioning

The FaceSign API uses date-based versioning. You can specify the API version using the FaceSign-Version header:

Specify API version

curl https://api.facesign.ai/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "FaceSign-Version: 2024-01-15"

If you don't specify a version, your requests will use the API version that was current when your account was created.

Webhook signatures

For webhook endpoints, verify the signature to ensure requests are from FaceSign:

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Next steps

Now that you understand authentication, you're ready to start making API requests:

Follow the quick start guide

Learn about sessions

Understand error handling