Authentication

The SourceVerify API supports two authentication modes. Both convey identity and scope of access — use the one that matches your integration shape.

Choosing a mode

Mode	When to use	Header
Bearer JWT	A user is signed in to your app and acting on their own data.	Authorization: Bearer <token>
API key	Server-to-server, scheduled jobs, agents, CI.	X-Api-Key: <key>

All API and DB access is scoped by userId. Admin-only endpoints additionally require role = "ADMIN".

Bearer JWT

Exchange email + password for a short-lived JWT:

curl -X POST https://api.sourceverify.app/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"..."}'

Then call the API:

curl https://api.sourceverify.app/v1/verifications \
  -H "Authorization: Bearer $JWT"

Refresh before expiry:

curl -X POST https://api.sourceverify.app/v1/auth/refresh \
  -H "Authorization: Bearer $REFRESH_TOKEN"

API key

API keys are issued from the dashboard and stored as a bcrypt hash on ApiKey.keyHash. The plaintext key is shown once at creation — keep it in your secret store.

curl https://api.sourceverify.app/v1/verifications \
  -H "X-Api-Key: $SOURCEVERIFY_API_KEY"

Rotation

• Generate a new key.
• Update your secret store.
• Wait for traffic on the old key to drain (monitor in dashboard).
• Revoke the old key.

Status codes

Code	Meaning
401 Unauthorized	Missing, malformed, or expired credential.
403 Forbidden	Credential is valid but the user lacks scope/role.
429 Too Many Requests	Rate limit exceeded (100 req/min per IP in production).