🔐 Authentication

Secure Bearer token authentication system

Overview

The API uses Bearer token authentication for secure access. All endpoints (except authentication endpoints) require a valid bearer token in the Authorization header.

🔑 Token Types

  • • Access Token: Main authentication token
  • • Token Type: Bearer
  • • Expires: 1 hour (3600 seconds)
  • • Scope: User-specific access

🛡️ Security Features

  • • Secure token generation
  • • Multiple session support
  • • Logout all devices capability

Login

POST /oauth/token 
POST /oauth/token
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123",
  "grant_type": "password"
}

Request Body Parameters

Parameter Type Required Description
email string ✓ User's email address
password string ✓ User's password
grant_type string ✓ Must be "password"

Success Response

200 OK 
{
  "access_token": "pYqGuLH2Jy7UZ6JJWPjssc8ZeBVtf7lMAp",
  "token_type": "Bearer",
  "expires_in": 3000,
}

Error Response

422 Unprocessable Entity 
{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "detail": "The provided credentials are incorrect.",
      "source": {
        "pointer": "/email"
      },
      "status": "422",
      "title": "Unprocessable Entity"
    }
  ]
}

Using the Access Token

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

GET /albums
Authorization: Bearer pYqGuLH2Jy7UZ6JJWPjssc8ZeBVtf7lMAp
Content-Type: application/vnd.api+json

Important

Always include the Bearer token in the Authorization header for authenticated requests. Store tokens securely and handle token expiration gracefully in your application.

Get Current User

GET /auth/me 
GET /auth/me
Authorization: Bearer {access_token}
Content-Type: application/json

Success Response

200 OK 
{
  "user": {
    "id": 13470,
    "name": "Test User",
    "email": "test@example.com",
    "created_at": "2021-08-13T18:55:30.000000Z",
    "updated_at": "2021-08-13T18:55:30.000000Z"
  }
}

Logout

Single Session Logout

Revoke the current access token:

POST /auth/logout 
POST /auth/logout
Content-Type: application/vnd.api+json
Authorization: Bearer {token}
200 OK 
{ "message": "Session closed successfully" }

All Sessions Logout

Revoke all user access tokens:

POST /auth/logout-all 
POST /auth/logout-all
Content-Type: application/vnd.api+json
Authorization: Bearer {token}
200 OK 
{ "message": "Session closed on all devices" }

🚀 Best Practices

🔐 Security

  • • Store tokens securely (avoid localStorage for sensitive apps)
  • • Use HTTPS in production environments
  • • Implement token refresh logic
  • • Handle 401 responses gracefully
  • • Log out users when tokens expire

⚡ Performance

  • • Cache user information after authentication
  • • Implement retry logic for network failures
  • • Use appropriate timeout values
  • • Monitor token usage and lifetime
  • • Clean up expired tokens regularly

🛠 Implementation

  • • Always check response status codes
  • • Implement proper error handling
  • • Use interceptors for automatic token attachment
  • • Validate tokens before making requests
  • • Provide clear authentication state feedback

🔄 Error Handling

  • • Handle 401 Unauthorized responses
  • • Show user-friendly error messages
  • • Implement exponential backoff for retries
  • • Log authentication errors for debugging