NeilClack
9e9cabfb2b
- Refresh AI guide docs (api, svelte-patterns, testing-patterns) - Add API updates notes, drop the outdated portal_api_v2_schema.md - Format package.json
2.6 KiB
API Documentation
Only read this file when modifying API routes, authentication, keys, or integrations.
API Location
API routes:
src/routes/api/v1/
Authentication
Most API endpoints require:
Authorization: Bearer
API keys are:
- generated randomly
- hashed with SHA-256 before storage
- displayed using stored prefix only
Never store plaintext API keys.
API Key Lifecycle
Normal rotation:
- New key generated.
- Old key remains valid for 48 hours.
- Old key expires using expiresAt.
Emergency rotation:
- Old key immediately invalidated.
- revokedAt is set.
API Routes
Categories
GET:
/api/v1/categories
Requires API key.
Frequencies
GET:
/api/v1/frequencies
Requires API key.
Proclamations
GET:
/api/v1/proclamations
Supports:
- optional key filtering
- optional email filtering
Requires API key.
License Validation
POST:
/api/v1/license
Payload:
{ "license_key": "...", "email_address": "..." }
Requires API key.
GHL Account Creation Webhook
Endpoint:
POST /api/v1/automations/create/account
This endpoint does NOT require an API key.
It is used by GoHighLevel automation.
Account Creation Flow
When a request arrives:
- Check whether the email already exists.
If user does not exist:
- Create user through Better Auth.
- Generate temporary password.
- Retrieve verification token.
- Build verification URL.
- Send registration email.
Then:
- Create LicenseKey.
- Send license key delivery email.
If user already exists:
- Skip signup.
- Create license key.
- Send delivery email.
Email Templates
Controlled by:
src/lib/server/resend.ts
Templates:
automated-user-registration
Variables:
- firstName
- tempPassword
- verifyUrl
- loginUrl
license-key-delivery
Variables:
- firstName
- license_key
email-verification-email
Variables:
- target_email_address
- verification_link
Better Auth
Server:
src/lib/auth.ts
Client:
src/lib/auth-client.ts
Email callbacks:
- sendVerificationEmail
- sendResetPassword
Failures should:
- log errors
- not crash requests
Use:
void promise.catch()
pattern.
Security Rules
Never:
- expose plaintext API keys
- bypass authorization checks
- trust client role information
- skip validation
Always:
- validate input
- check permissions
- preserve existing security patterns
API Change Workflow
Before modifying an endpoint:
- Read the route.
- Read related auth middleware.
- Read database models involved.
- Check existing tests.
After modifying:
Run:
npm run check npm run test
Fix failures before completing.