Backend API Overview¶

The Inklet backend exposes a RESTful JSON API for authentication, device management, and billing. The backend is built with Go and the Chi router.

Base URL¶

Environment	URL
Production	`https://auth.iminklet.com`
Local	`http://localhost:4000`

Response Format¶

All responses return JSON with appropriate HTTP status codes. Successful responses use 200 or 201; errors return a JSON body with a message field:

{
  "message": "description of the error"
}

Authentication¶

Protected endpoints require a valid JWT access token in the Authorization header:

Authorization: Bearer {accessToken}

Access tokens are short-lived. Use the refresh endpoint to obtain new tokens without re-authenticating.

Token Lifecycle

Access tokens expire after a short window (typically 15 minutes). Refresh tokens are long-lived but are rotated on each use --- the old refresh token is invalidated when a new pair is issued.

API Groups¶

The API is organized into three groups:

Auth (`/auth/*`)¶

User registration, login, OAuth (Google and Apple), session management, profile updates, and subscription billing.

See: Authentication | Billing

Devices (`/api/devices/*`)¶

Device listing, binding (NFC and claim code), unbinding, command delivery, and state retrieval.

See: Devices

Health (`/health`)¶

A simple health check endpoint used by load balancers and monitoring.

curl https://auth.iminklet.com/health

{
  "status": "ok"
}

Common HTTP Status Codes¶

Code	Meaning
`200`	Success
`201`	Resource created
`400`	Bad request --- invalid or missing fields
`401`	Unauthorized --- missing or expired token
`403`	Forbidden --- you do not own this resource
`404`	Resource not found
`409`	Conflict --- duplicate email, username, or device already bound
`410`	Gone --- resource has been deleted or expired
`500`	Internal server error

Rate Limiting¶

API requests may be rate-limited in production. If you exceed the limit, you will receive a 429 Too Many Requests response. Back off and retry after the Retry-After header value.

CORS¶

The production backend allows cross-origin requests from https://portal.iminklet.com. Local development allows http://localhost:5173.