Identity And Access Management

The server should reject unknown fields if strict request validation is enabled. It must not return the submitted password in logs or responses.

Code Example

`bash

Credentials must be sent over HTTPS. curl -X POST "https://api.example.com/v1/auth/login" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "identifier": "dev@example.com", "password": "correct-horse-battery-staple", "remember": true, "device_name": "web-browser" }' `

A client should store the access token according to its platform security model, attach it to subsequent protected requests, and use the refresh token only at the token-refresh endpoint.

Response Format

A successful response contains bearer credentials and basic authenticated-user data:

json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 900, "refresh_token": "rt_01J8Q7Y6K2...", "user": { "id": "usr_01J8Q6Z4M9", "identifier": "dev@example.com", "status": "active" } }

| Field | Type | Description | |---|---|---| | access_token | string | Short-lived token for protected API requests. | | token_type | string | Authorization scheme; currently Bearer. | | expires_in | integer | Access-token lifetime in seconds. | | refresh_token | string | Credential used to obtain a new access token. | | user | object | Minimal authenticated-user representation. |

Failure responses should use a stable error envelope:

json { "error": { "code": "invalid_credentials", "message": "The identifier or password is incorrect.", "request_id": "req_01J8Q8A2P4" } }

Notes & Best Practices

• Return the same 401 response for an unknown identifier and an incorrect password to reduce account enumeration. - Apply per-IP and per-identifier rate limits; return 429 with Retry-After when limits are exceeded. - Use constant-time password-hash verification and never log passwords, raw tokens, or full authentication payloads. - Revoke refresh tokens on logout, password reset, or suspicious-session detection; treat 403 account-status errors separately from invalid credentials.

A predictable login contract makes token handling, failure recovery, and later authorization decisions consistent across clients.

End of chapter one. 39 more chapters in the full book.