Authentication
VerifyAI uses API keys for authentication. Every request to the REST API
must include an X-API-Key header with a valid key for an active
subscription.
API key format
Keys are prefixed strings, currently in the vai_ namespace:
vai_live_8x9k2m4n7p3q5w8r1t6y2u4i9o0a3sWhere you find them:
- Dashboard → Settings → API keys — create, rotate, and revoke keys.
- Sandbox keys — issued when you sign up; usage is free and never bills your account.
Anyone with a key can submit verifications against your subscription. Rotate keys immediately if one leaks, and prefer running requests from your backend whenever possible.
Authenticating a request
Pass the key in the X-API-Key header:
curl https://verify.switchlabs.dev/api/v1/verifications \
-H "X-API-Key: vai_your_api_key"The SDKs pass this header for you when you initialize a client:
import { useVerifyAI } from "@switchlabs/verify-ai-react-native";
const { verify } = useVerifyAI({ apiKey: process.env.EXPO_PUBLIC_VERIFY_AI_KEY });Auth-related errors
| Status | Body | When this happens |
| ------ | -------------------------------------- | ------------------------------------------------------------ |
| 401 | { "error": "Missing API key" } | The X-API-Key header was not sent. |
| 401 | { "error": "Invalid API key format" }| Header value doesn't match the expected vai_ prefix. |
| 401 | { "error": "Invalid API key" } | Unknown, revoked, or disabled key. |
| 403 | { "error": "API key not valid for Verify AI" } | Key belongs to a different Switch Labs product. |
| 403 | { "error": "No active Verify AI subscription" } | Subscription is paused, cancelled, or past due. |
| 429 | { "error": "Rate limit exceeded" } | Throttled. See Retry-After header. |
| 429 | Monthly usage limit reached | Included verifications exhausted; upgrade or wait for reset. |
Every response also includes an X-Request-Id header. Include the ID
when contacting support — it speeds up diagnostics significantly.
Rotating keys
- Open Dashboard → Settings → API keys.
- Click Create key to generate a new key.
- Update your deployments to use the new key.
- Revoke the old key once you've confirmed no production traffic still uses it.
We recommend rotating production keys every 90 days, and immediately if a key is ever exposed.
Mobile keys
If you embed a key in a mobile binary, treat it as semi-public. Set the key's permissions to verify-only (no list / no delete) from the dashboard, monitor usage for anomalies, and rotate after each major app release.