Skip to main content

​
Overview

The Prompts.dev API uses JWT (JSON Web Token) based authentication to secure endpoints. After logging in via OAuth, you’ll receive a JWT token that must be included in subsequent API requests.

​
Token Format

JWT tokens are issued using the HS256 signing algorithm and contain the following claims:
​
user_id
string
required
The unique identifier of the authenticated user
​
sub
string
required
Subject claim (same as user_id)
​
iat
number
required
Issued at timestamp (Unix time)
​
exp
number
required
Expiration timestamp (Unix time)
Tokens expire after a configured period (typically 24-72 hours). The exact expiration time is set by the JWT_EXPIRY_HOURS environment variable on the server.

​
Token Verification

Tokens are verified using the server’s JWT secret. The authentication middleware:
  1. Extracts the token from the Authorization header
  2. Validates the token signature using HS256
  3. Checks the expiration time
  4. Extracts the user_id claim and adds it to the request context
Reference: internal/auth/token.go:29 and internal/auth/middleware.go:23

​
Making Authenticated Requests

To authenticate API requests, include your JWT token in the Authorization header using the Bearer scheme: 
curl https://api.prompts.dev/v1/prompts \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-prompt",
    "description": "A helpful prompt",
    "visibility": "public"
  }'

​
Authentication Errors

If authentication fails, the API returns a 401 Unauthorized response:

​
Missing Token

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "missing bearer token"
  }
}

​
Invalid or Expired Token

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "invalid access token"
  }
}
The middleware automatically aborts the request and returns an error response when authentication fails. No further processing occurs.

​
Protected Endpoints

The following endpoints require authentication:
  • POST /v1/prompts - Create a new prompt
  • POST /v1/prompts/:id/versions - Upload a new version
Reference: cmd/api/main.go:60

​
Extracting User Information

In authenticated requests, the user ID is available in two ways: From Gin Context: 
userID, ok := auth.UserIDFromGin(c)
if !ok {
    // handle missing user ID
}
From Standard Context: 
userID, ok := auth.UserIDFromContext(ctx)
if !ok {
    // handle missing user ID
}
Reference: internal/auth/middleware.go:47

Build docs developers (and LLMs) love

Get started for freeTalk to us