Skip to content
AskVault Docs
Try Free →

Identity verification API

Written by , Founder, AskVault · Reviewed by Aashiq
Last updated: · 3 min read

Endpoints

Three core endpoints:

GET    /v1/identity-verification          # Get current config
PATCH  /v1/identity-verification          # Update config (enable/disable, secret)
POST   /v1/identity-verification/test     # Test a hash

Get config

Terminal window
curl https://api.askvault.co/v1/identity-verification \
  -H "Authorization: Bearer ak_xxx"

Returns:

{
  "enabled": true,
  "secret_hash": "sha256:abc...",
  "rotated_at": "2026-05-01T00:00:00Z",
  "grace_period_ends_at": null
}

secret_hash is a hash of the secret (we don't expose the secret itself via API).

Update config

Enable enforcement:

Terminal window
curl -X PATCH https://api.askvault.co/v1/identity-verification \
  -H "Authorization: Bearer ak_xxx" \
  -d '{"enabled":true}'

Regenerate secret:

Terminal window
curl -X POST https://api.askvault.co/v1/identity-verification/rotate \
  -H "Authorization: Bearer ak_xxx"

Returns the new secret once (not stored for re-retrieval).

Test endpoint

Verify a computed hash:

Terminal window
curl -X POST https://api.askvault.co/v1/identity-verification/test \
  -H "Authorization: Bearer ak_xxx" \
  -d '{"user_id":"u_123","hash":"abc..."}'

Returns {"valid": true} or {"valid": false}.

Useful for backend testing.

HMAC computation

The hash is HMAC-SHA256(secret, user_id):

import hmac, hashlib
hash_value = hmac.new(secret.encode(), user_id.encode(), hashlib.sha256).hexdigest()
const crypto = require('crypto');
const hashValue = crypto.createHmac('sha256', secret).update(userId).digest('hex');

See identity verification setup for full implementation.

Rotation flow

Rotate every 6 to 12 months:

  1. Call rotate endpoint. Returns new secret.
  2. 24-hour grace period: old plus new both verify.
  3. Update your backend to use new secret.
  4. After grace, old retires.

Webhook on failed verification

For monitoring:

  • identity.verification_failed webhook fires on rejected attempts.
  • Useful for spotting brute-force or misconfigured backends.

Limits

  • Rotations per month. 10 (anti-thrashing).
  • Test endpoint rate. 100 requests per minute.
  • Grace period. 24 hours fixed.
  • HMAC secret length. 64 characters.
  • API response time. Under 200 ms.

Common pitfalls

Test endpoint returns invalid for valid hash. Encoding mismatch (UTF-8 vs ASCII). Check both sides.

Rotation breaks production. Don't rotate without parallel update. Use grace period.

Test endpoint counted as API quota. Yes; budget accordingly during heavy debugging.

FAQ

Is the test endpoint safe in production?

Yes. Doesn't affect actual conversations. Useful for monitoring.

Can I disable verification mid-cycle?

Yes via PATCH {"enabled":false}. Visitors no longer need to verify.

Does failed verification log?

Yes in audit log plus webhook event.

Was this page helpful?