portal/docs/ai/api.md

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.

---

Schedule (v2)

Endpoint:

GET /api/v2/schedule?email=&licenseKey=

Authenticates with the paired email + licenseKey query parameters and validates only that the key belongs to the account (not that the license is active/entitled). Returns the user's Blocks with start/end times and the IDs of the selected Proclamations (content is fetched separately via /api/v2/proclamations). Overnight blocks (end clock time before start) are supported and flagged with overnight: true plus a wrapping durationMinutes. Rate limited to 10 requests per minute per IP. Failure messages follow the existing v2 shape: not-authorized or this key doesn't appear to belong to you.

---

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:

1. Check whether the email already exists.

If user does not exist:

2. Create user through Better Auth.
3. Generate temporary password.
4. Retrieve verification token.
5. Build verification URL.
6. Send registration email.

Then:

7. Create LicenseKey.
8. Send license key delivery email.

If user already exists:

1. Skip signup.
2. Create license key.
3. 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:

1. Read the route.
2. Read related auth middleware.
3. Read database models involved.
4. Check existing tests.

After modifying:

Run:

npm run check npm run test

Fix failures before completing.