API Authentication
Learn how to authenticate with the Owl Eyes API using API keys.
API Keys
Owl Eyes uses API keys to authenticate requests. You have two types of keys:
Publishable Key (pk_)
Safe to expose in frontend code. Used to initialize the SDK and create client-side verification sessions.
pk_live_abc123...Secret Key (sk_)
Must be kept secret. Used for server-side API calls, creating verification links, and accessing sensitive data.
sk_live_xyz789...Getting Your API Keys
Navigate to API Access
Go to Dashboard → API Access.
View Your Keys
Your publishable key is visible. Click "Reveal" to view your secret key.
Copy and Store Securely
Copy your keys and store them in environment variables or a secrets manager.
Authentication Methods
Bearer Token (Recommended)
Pass your secret key in the Authorization header:
Query Parameter
Alternatively, pass the key as a query parameter (not recommended for production):
Using API Keys in Code
Node.js
Python
Go
Test vs Live Keys
Each environment has its own set of API keys:
| Environment | Key Prefix | Use Case |
|---|---|---|
| Test/Sandbox | pk_test_ / sk_test_ | Development, testing, CI/CD |
| Live/Production | pk_live_ / sk_live_ | Production applications |
Test keys work with the sandbox API and don't process real verifications. Use them during development to avoid charges.
Rolling API Keys
If your secret key is compromised, roll it immediately:
Generate New Key
In the dashboard, click "Roll Secret Key" to generate a new key.
Grace Period
Both old and new keys work for 24 hours to allow migration.
Update Your Application
Update your environment variables or secrets manager with the new key.
Revoke Old Key
After confirming the new key works, revoke the old key immediately.
IP Allowlisting
For additional security, restrict API access to specific IP addresses:
You can also configure this in the dashboard under API Access → Security Settings.
Authentication Errors
| Status | Error | Description |
|---|---|---|
| 401 | invalid_api_key | API key is invalid or malformed |
| 401 | expired_api_key | API key has been revoked |
| 403 | insufficient_permissions | Key doesn't have access to this resource |
| 403 | ip_not_allowed | Request from unauthorized IP address |
Best Practices
Use environment variables
Never hardcode API keys in your source code.
Use a secrets manager
Store keys in AWS Secrets Manager, HashiCorp Vault, or similar.
Use different keys per environment
Separate test and production keys. Don't share across environments.
Enable IP allowlisting
Restrict API access to your server's IP addresses.
Rotate keys regularly
Roll keys periodically as a security best practice.