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": "YourPassword1",
  "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

Requests that carry a body — POST and PATCH on any resource — also need Content-Type: application/vnd.api+json. Without it the response is 415.

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}

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
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
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