HeroPrompt
Back to docs
API Reference

API Authentication

How to authenticate with the HeroPrompt API using JWT tokens.

Updated 2026-02-15

API Authentication

The HeroPrompt API uses JWT (JSON Web Tokens) for authentication. This guide covers registration, login, and using tokens in API requests.

Authentication Methods

1. Email & Password

Traditional email/password authentication with bcrypt-hashed passwords.

2. GitHub OAuth

Single Sign-On via GitHub account.

3. Google OAuth

Single Sign-On via Google account.

Getting a JWT Token

Option 1: Email/Password Registration

http
POST https://heroprompt.store/api/auth/register
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "SecurePassword123!",
  "name": "Your Name"
}

Response:

json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "user-abc-123",
    "email": "you@example.com",
    "name": "Your Name",
    "tier": "free"
  }
}

Option 2: Email/Password Login

http
POST https://heroprompt.store/api/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "SecurePassword123!"
}

Response: Same as registration — returns access_token and user object.

Option 3: GitHub OAuth

  1. Initiate OAuth:
http
GET https://heroprompt.store/api/auth/github

This redirects to GitHub's authorization page.

  1. Callback:

After authorization, GitHub redirects to /api/auth/callback/github with a code. The backend exchanges the code for a JWT.

  1. Frontend receives token:

The token is returned to your frontend at the redirect URL.

Option 4: Google OAuth

  1. Initiate OAuth:
http
GET https://heroprompt.store/api/auth/google

This redirects to Google's authorization page.

  1. Callback:

After authorization, Google redirects to /api/auth/callback/google with a code. The backend exchanges the code for a JWT.

  1. Frontend receives token:

The token is returned to your frontend at the redirect URL.

Using JWT Tokens

Include the token in the Authorization header for all authenticated requests:

http
GET https://heroprompt.store/api/user/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Format

text
Authorization: Bearer <jwt_token>

Important: Include the Bearer prefix before the token.

Token Properties

  • Algorithm: HS256 (HMAC with SHA-256)
  • Expiry: 7 days from issuance
  • Payload includes:
  • user_id — User's unique identifier
  • email — User's email address
  • exp — Expiration timestamp (Unix epoch)

Token Expiry and Renewal

JWT tokens expire after 7 days. When a token expires:

  1. API returns 401 Unauthorized
  2. Client must re-authenticate via login or OAuth
  3. A new token is issued

There is no refresh token mechanism — users must log in again when the token expires.

Personal Access Tokens (PATs)

For CLI and programmatic access, use Personal Access Tokens instead of JWT:

Creating a PAT

http
POST https://heroprompt.store/api/user/tokens
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "name": "My Dev Machine",
  "expires_in_days": 90
}

Response:

json
{
  "token_id": "tok_abc123",
  "token": "hp_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "My Dev Machine",
  "expires_at": "2026-05-15T10:00:00Z"
}

⚠️ Important: Copy the token immediately — it's only shown once.

Using a PAT

http
GET https://heroprompt.store/api/user/me
Authorization: Bearer hp_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

PATs work exactly like JWT tokens but have longer expiry (90 days by default).

Token Limits by Tier

TierMax PATs
Free0
Starter1
Pro Kit3
Lifetime5

Error Handling

401 Unauthorized

Causes:

  • Missing Authorization header
  • Invalid token format
  • Expired token
  • Token for deleted user

Solution: Re-authenticate and get a new token.

403 Forbidden

Causes:

  • Valid token, but insufficient permissions
  • Tier upgrade required (e.g., trying to access Skills on Free tier)

Solution: Upgrade your subscription at /pricing.

Security Best Practices

DO:

✅ Store tokens securely — Use httpOnly cookies or secure storage (not localStorage for sensitive apps)

✅ Use HTTPS — Never send tokens over unencrypted connections

✅ Rotate tokens regularly — Set PAT expiry to 90 days max

✅ Revoke unused tokens — Delete PATs you're not using

DON'T:

❌ Commit tokens to git — Add .env to .gitignore

❌ Share tokens — Each user/machine should have their own

❌ Log tokens — Sanitize logs before storage

❌ Embed in client code — Tokens should be server-side or injected at runtime

Testing Authentication

Test with cURL

bash
# Login
curl -X POST https://heroprompt.store/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"password"}'

# Use the returned token
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
curl https://heroprompt.store/api/user/me \
  -H "Authorization: Bearer $TOKEN"

Test with Postman

  1. Create request → POST /api/auth/login
  2. Add body → JSON with email and password
  3. Send request → Copy access_token from response
  4. Set up auth → Add Authorization: Bearer <token> to headers
  5. Test endpoints → Make authenticated requests

Next Steps

Previous
Syncing Prompts
Next
Endpoints