API Reference — User Authentication API
Authenticate users, issue tokens, and manage sessions. Version v1. Base URL: https://api.example.com/v1.
Audience: developers integrating login, registration, and session management. Auth method: Bearer token. Content type: all requests and responses use application/json. Rate limit: 100 requests per minute per API key; 10 login attempts per minute per IP. Environments: Sandbox at https://api-sandbox.example.com/v1, Production at https://api.example.com/v1.
Tip: Build against the sandbox first. Sandbox keys start with sk_test_ and never touch real user data. Production keys start with sk_live_.
Authentication
Every request after login must include your access token in the Authorization header.
Request headers for all authenticated endpoints:
Authorization: Bearer, followed by your access token. Required.
Content-Type: application/json. Required.
X-API-Key: your API key, for example sk_live_4f2k and so on. Required.
How tokens work:
Client sends POST /auth/login. The API returns an access token (15 minutes) and a refresh token (30 days).
Client sends GET /auth/me with Authorization: Bearer and the access token.
When the access token expires, client sends POST /auth/refresh and receives a new access token.
Warning: Never send tokens in a URL query string, and never log the Authorization header. Tokens in URLs end up in server logs, browser history, and analytics tools.
Endpoints
2.1 Register a user — POST /auth/register
Creates a new user account and returns an access token immediately.
Request headers: Content-Type application/json; X-API-Key sk_live_ and so on.
Parameters:
email, string, required. User's email address. Must be unique and valid format. Max 254 characters.
password, string, required. Minimum 12 characters; must include one uppercase letter, one number, and one symbol.
name, string, required. Display name. 2 to 80 characters.
plan, string, optional. Subscription plan. One of free, pro, team. Default: free.
referral_code, string, optional. Referral code. 6 to 12 alphanumeric characters.
Sample request:
POST /v1/auth/register
{
"email": "ana@example.com",
"password": "Sunset!River42",
"name": "Ana Rivera",
"plan": "pro"
}
Sample response — 201 Created:
{
"user": {
"id": "usr_9f2k1n7q",
"email": "ana@example.com",
"name": "Ana Rivera",
"plan": "pro",
"created_at": "2026-11-07T09:14:00Z"
},
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "rft_8k2m4n6p1q3s5t7v...",
"token_type": "Bearer",
"expires_in": 900
}
2.2 Log in — POST /auth/login
Authenticates a user and returns tokens. Limited to 10 attempts per minute per IP.
Parameters:
email, string, required. The email used at registration.
password, string, required. The user's password.
remember_me, boolean, optional. If true, the refresh token lasts 90 days instead of 30. Default: false.
Sample request:
POST /v1/auth/login
{
"email": "ana@example.com",
"password": "Sunset!River42",
"remember_me": false
}
Sample response — 200 OK:
{
"user": {
"id": "usr_9f2k1n7q",
"email": "ana@example.com",
"name": "Ana Rivera",
"plan": "pro"
},
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "rft_8k2m4n6p1q3s5t7v...",
"token_type": "Bearer",
"expires_in": 900
}
2.3 Refresh a token — POST /auth/refresh
Exchanges a valid refresh token for a new access token. Use this before the access token expires — do not make the user log in again.
Parameters:
refresh_token, string, required. The refresh token returned by /auth/login or /auth/register.
Sample request:
POST /v1/auth/refresh
{
"refresh_token": "rft_8k2m4n6p1q3s5t7v..."
}
Sample response — 200 OK:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 900
}
Note: Refresh tokens are single-use. Each call returns the same refresh token until it expires, then the user must log in again. If a refresh token is used twice, all tokens for that user are revoked as a security precaution.
2.4 Get the current user — GET /auth/me
Returns the profile of the user who owns the access token.
Request headers: Authorization Bearer and the access token; X-API-Key sk_live_ and so on.
Parameters: None. The user is identified by the token.
Sample response — 200 OK:
{
"id": "usr_9f2k1n7q",
"email": "ana@example.com",
"name": "Ana Rivera",
"plan": "pro",
"email_verified": true,
"created_at": "2026-11-07T09:14:00Z",
"last_login_at": "2026-11-07T09:31:00Z"
}
2.5 Log out — POST /auth/logout
Revokes the current access token and refresh token immediately.
Request headers: Authorization Bearer and the access token; X-API-Key sk_live_ and so on.
Parameters: None.
Sample response — 200 OK:
{
"message": "Logged out successfully."
}
Response codes
200 OK: Success. Login, refresh, profile fetch, and logout completed. Nothing to do — process the response body.
201 Created: Resource created. Registration completed. Store the returned tokens.
400 Bad Request: Invalid input. Missing field, bad email format, password too weak. Read the details array — it names the exact field; fix and resend.
401 Unauthorized: Auth failed. Missing, expired, or revoked token; wrong API key. Refresh the token; if that fails, ask the user to log in again.
403 Forbidden: Not allowed. Token is valid but the account is suspended or the plan does not include this action. Check the account status; upgrade the plan if the action requires it.
404 Not Found: No such route. Wrong URL, or a mistyped endpoint path. Check the path against Section 2; confirm you are on the right environment.
429 Too Many Requests: Rate limited. More than 100 requests per minute, or more than 10 login attempts per minute per IP. Wait the seconds in the Retry-After header, then resume slowly.
500 Internal Server Error: Server fault. A fault on the API side. Retry once after 60 seconds with backoff; if it repeats, open a support ticket with the request ID.
Error response format (same shape for every error):
{
"error": "invalid_credentials",
"message": "Email or password is incorrect.",
"details": [
{ "field": "password", "issue": "does not match the stored password" }
],
"request_id": "req_8f2k1n9q"
}
Fields: error — short machine-readable code, use this in your code, not the message. message — human-readable explanation, safe to show to users. details — array of field-level problems, empty for errors that are not field-specific. request_id — include this in every support ticket; support finds the exact request from it.
Common error examples
400 — weak password:
{
"error": "validation_failed",
"message": "Password does not meet the requirements.",
"details": [
{ "field": "password", "issue": "must include one uppercase letter, one number, and one symbol" }
],
"request_id": "req_8f2k1n9q"
}
401 — expired token:
{
"error": "token_expired",
"message": "Access token has expired. Refresh it or log in again.",
"details": [],
"request_id": "req_8f2k1n9q"
}
500 — server fault:
{
"error": "internal_error",
"message": "Something went wrong on our side. Please retry shortly.",
"details": [],
"request_id": "req_8f2k1n9q"
}
Best practices
Store tokens securely. Access tokens in memory only; refresh tokens in secure, HTTP-only storage. Never in localStorage on a public page.
Refresh early. Refresh the access token when 5 minutes remain, not after it expires. Users never see a session drop.
Handle 401 by refreshing once. On a 401, call /auth/refresh a single time and retry the original request. If the refresh also fails, send the user to login — do not loop.
Send the request ID with every support ticket. It is the fastest path to a fix.
Respect the login rate limit. Ten failed logins per minute per IP triggers a temporary block. Show a captcha after 3 failed attempts instead of letting users hammer the endpoint.
Test with the sandbox. Sandbox keys (sk_test_) behave identically to production, including errors. Every error in Section 3 can be reproduced there safely.
Rate limits and versioning
General requests: 100 per minute per API key. Watch the X-RateLimit-Remaining header.
Login attempts: 10 per minute per IP. Watch the Retry-After header (seconds).
Webhook deliveries: 1,000 per hour per endpoint.
Versioning: the version is in the URL (/v1/). Breaking changes ship as a new version; v1 keeps working for at least 12 months after v2 launches.
Changelog: breaking changes are announced 30 days in advance by email and in the developer changelog.
Sample documentation prepared as a portfolio piece. All URLs, keys, tokens, user data, and request IDs are fictional examples. Always confirm current limits, token lifetimes, and endpoint paths against the live API documentation.
0 likes · 0 views · Nov 7, 2026
API reference for user authentication: 5 endpoints, parameter tables, sample requests, and response codes from 200 to 500.
