Authentication

Reevit uses API keys for server-to-server authentication.

API Keys

Format

pfk_live_a1b2c3d4e5f6g7h8i9j0.secret
pfk_test_a1b2c3d4e5f6g7h8i9j0.secret

pfk_live_ — Production keys
pfk_test_ — Sandbox/test keys

Creating Keys

curl -X POST https://api.reevit.io/v1/api-keys \
  -H "X-Reevit-Key: pfk_live_xxx.secret" \
  -H "X-Org-Id: org_123" \
  -H "Idempotency-Key: key-create-001" \
  -d '{
    "name": "Backend Production",
    "scopes": ["payments:read", "payments:write"]
  }'

Response:

{
  "id": "key_abc123",
  "name": "Backend Production",
  "key": "pfk_live_a1b2c3d4e5f6g7h8i9j0.secret",
  "scopes": ["payments:read", "payments:write"],
  "created_at": "2025-02-10T10:00:00Z"
}

⚠️ Important: The full key is only shown once. Store it securely!

Listing Keys

curl https://api.reevit.io/v1/api-keys \
  -H "X-Reevit-Key: pfk_live_xxx.secret" \
  -H "X-Org-Id: org_123"

Revoking Keys

curl -X DELETE https://api.reevit.io/v1/api-keys/key_abc123 \
  -H "X-Reevit-Key: pfk_live_xxx.secret" \
  -H "X-Org-Id: org_123"

Required Headers

Header	Required	Description
`X-Reevit-Key`	Yes	Your API key
`X-Org-Id`	Yes	Your organization ID
`X-Reevit-Client-Version`	Recommended	SDK/Client version for tracking
`Idempotency-Key`	For mutations	Unique request identifier
`Content-Type`	For POST/PATCH	`application/json`
`X-Actor-Id`	Optional	User ID for audit logs

Example Request

curl -X POST https://api.reevit.io/v1/payments/intents \
  -H "X-Reevit-Key: pfk_live_xxx.secret" \
  -H "X-Org-Id: org_123" \
  -H "Idempotency-Key: order-12345" \
  -H "X-Actor-Id: user_789" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "currency": "GHS"}'

Scopes

API keys are scoped to limit access:

Scope	Permissions
`connections:read`	View PSP connections
`connections:write`	Create/update/delete connections
`payments:read`	View payments and stats
`payments:write`	Create/confirm/refund payments
`fraud:read`	View fraud policies
`fraud:write`	Update fraud policies
`webhooks:read`	View webhook events and config
`webhooks:write`	Configure webhooks, replay events
`subscriptions:read`	View subscriptions
`subscriptions:write`	Create/update/cancel subscriptions
`invoices:read`	View invoices
`invoices:write`	Retry/cancel invoices
`api_keys:read`	List API keys
`api_keys:write`	Create/revoke API keys
`workflows:read`	View workflow automation
`workflows:write`	Manage workflows

Scope Errors

If you call an endpoint without the required scope:

{
  "error": "forbidden",
  "message": "API key missing required scope: payments:write"
}

Idempotency

All mutation endpoints (POST, PATCH, DELETE) require an Idempotency-Key header.

How It Works

First request with key order-12345 → Processed, response cached
Retry with same key → Cached response returned (no duplicate)
Different key → New request processed

Best Practices

Use unique, deterministic keys (e.g., order-{order_id})
Keys are valid for 24 hours
Include enough context to be unique

# Good: Deterministic, unique per order
Idempotency-Key: order-12345

# Bad: Random, can't retry safely
Idempotency-Key: abc123xyz

Error Responses

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

{
  "error": "forbidden",
  "message": "API key missing required scope"
}

429 Too Many Requests

{
  "error": "rate_limited",
  "message": "Too many requests",
  "retry_after": 60
}

Security Best Practices

Never expose keys in client-side code — Use server-to-server calls only
Use environment variables — Don’t commit keys to version control
Rotate keys regularly — Create new keys and revoke old ones
Use minimal scopes — Only grant permissions you need
Monitor usage — Check dashboard for unusual activity

Session Authentication

For dashboard and web applications, Reevit supports session-based authentication:

Magic Link Authentication

Request a magic link:

curl -X POST https://api.reevit.io/v1/auth/magic-link \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

User clicks link in email, which calls:

GET https://api.reevit.io/v1/auth/verify?token=xxx

Session cookie is set automatically (reevit_session)

Two-Factor Authentication (2FA)

Users can enable TOTP-based 2FA:

# Setup 2FA
POST /v1/auth/2fa/setup

# Enable with verification code
POST /v1/auth/2fa/enable
{"code": "123456"}

# Login with 2FA
GET /v1/auth/verify?token=xxx&code=123456

WebAuthn/Passkeys

Passwordless authentication using WebAuthn:

# Register passkey
POST /v1/auth/webauthn/register/begin
POST /v1/auth/webauthn/register/finish

# Authenticate with passkey
POST /v1/auth/webauthn/authenticate/begin
POST /v1/auth/webauthn/authenticate/finish

Platform Admin Authentication

Platform administrators have elevated access across all organizations:

Role	Permissions
`platform_admin`	View/manage all organizations, approve/reject KYC
`platform_owner`	All platform_admin permissions + manage platform admins

Platform admin endpoints require session authentication and platform admin role:

# Check platform admin status
GET /v1/platform/me

# List all organizations (platform admin only)
GET /v1/platform/organizations

# Approve KYC (platform admin only)
POST /v1/platform/kyc/approve
{"org_id": "org_123"}

Platform admin actions are logged in the platform audit log for compliance.

Get Started

Core Features

Developer Resources

Authentication

Authentication

API Keys

Format

Creating Keys

Listing Keys

Revoking Keys

Required Headers

Example Request

Scopes

Scope Errors

Idempotency

How It Works

Best Practices

Error Responses

401 Unauthorized

403 Forbidden

429 Too Many Requests

Security Best Practices

Session Authentication

Magic Link Authentication

Two-Factor Authentication (2FA)

WebAuthn/Passkeys

Platform Admin Authentication

​Authentication

​API Keys

​Format

​Creating Keys

​Listing Keys

​Revoking Keys

​Required Headers

​Example Request

​Scopes

​Scope Errors

​Idempotency

​How It Works

​Best Practices

​Error Responses

​401 Unauthorized

​403 Forbidden

​429 Too Many Requests

​Security Best Practices

​Session Authentication

​Magic Link Authentication

​Two-Factor Authentication (2FA)

​WebAuthn/Passkeys

​Platform Admin Authentication

Authentication

API Keys

Format

Creating Keys

Listing Keys

Revoking Keys

Required Headers

Example Request

Scopes

Scope Errors

Idempotency

How It Works

Best Practices

Error Responses

401 Unauthorized

403 Forbidden

429 Too Many Requests

Security Best Practices

Session Authentication

Magic Link Authentication

Two-Factor Authentication (2FA)

WebAuthn/Passkeys

Platform Admin Authentication