Howler Basic Authentication API
The Basic Authentication API from Howler — 4 operation(s) for basic authentication.
OpenAPI Specification
openapi: 3.1.0
info:
title: Howler API v3 Artists Basic Authentication API
version: 3.6.1
description: '*Last updated: 2026-01-20 21:15:49 +0200*
'
servers:
- url: https://{defaultHost}/api/v3/consumer_portal
variables:
defaultHost:
default: www.howler.co.za
description: Server for consumer portal endpoints
security:
- bearer_header: []
bearer_param: []
api_key: []
bearer_auth: []
tags:
- name: Basic Authentication
paths:
/login:
post:
summary: User Login
tags:
- Basic Authentication
security: []
operationId: loginUser
parameters: []
description: 'Creates a new user session in and returns a JSON web token
'
responses:
'200':
description: Successful login
content:
application/json:
examples:
Successful login:
value:
user:
id: 1
first_name: Derek
last_name: The Admin
primary_email: admin@example.com
dummy?: false
token: eyJhbGciOiHIUzI1NiJ7.eyJ1c2VyX2lkIjoxLCJleHAiOjQ4OTUwMTkzNDh9.DdjO_nag9cJq45UqPIvWEjwE0yvyqtjTYzfpg_R9eg8
schema:
type: object
properties:
user:
type: object
properties:
id:
type: integer
email:
type: string
first_name:
type: string
last_name:
type: string
primary_email:
type: string
dummy?:
type: boolean
required:
- id
- primary_email
- first_name
- last_name
- primary_email
- dummy?
token:
type: string
required:
- user
- token
'401':
description: Authentication failed
content:
application/json:
examples:
Invalid credentials:
value:
status: 401
message: Invalid email or password.
schema:
type: object
properties:
status:
type: integer
message:
type: string
required:
- status
- message
requestBody:
content:
application/json:
schema:
type: object
properties:
user:
type: object
properties:
email:
type: string
password:
type: string
required:
- email
- password
required:
- user
examples:
Login request:
summary: Valid login request
value:
user:
email: Test@howler.co.za
password: password123
Invalid credentials request:
summary: Invalid login request
value:
user:
email: user@howler.co.za
password: wrongpassword
required: true
/jwt/ott:
post:
summary: Create a one-time token using JWT authentication
tags:
- Basic Authentication
operationId: createConsumerJWTOneTimeToken
responses:
'200':
description: one time token created
content:
application/json:
schema:
type: object
properties:
access_token:
type: string
example: a7d21ee5-5fff-4097-8884-33a6c1762480
token_type:
type: string
example: Bearer
expires_in:
type: integer
example: 300
created_at:
type: integer
example: 1647245673
required:
- access_token
- token_type
- expires_in
- created_at
'401':
description: unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: JWT authentication required
required:
- error
/password/reset:
post:
summary: Reset Password
tags:
- Basic Authentication
security: []
operationId: resetPassword
parameters: []
description: 'Requests a password reset email to be sent to the provided email address
'
responses:
'201':
description: Password reset request for non-existent email
content:
application/json:
examples:
Successful password reset request:
value:
status: success
message: Password reset instructions have been sent to your email
Non-existent email (still returns success):
value:
status: success
message: If your email exists in our system, password reset instructions have been sent
schema:
type: object
properties:
status:
type: string
message:
type: string
required:
- status
- message
'422':
description: Invalid email format
content:
application/json:
examples:
Missing email parameter:
value:
status: 422
error: Email is required
Missing user parameter:
value:
status: 422
error: Request must include a "user" object with an "email" field
Invalid email format:
value:
status: 422
error: Invalid email format
schema:
type: object
properties:
status:
type: integer
error:
type: string
required:
- status
- error
'500':
description: Server error during email delivery
content:
application/json:
examples:
Server error:
value:
status: 500
error: Failed to process password reset request
schema:
type: object
properties:
status:
type: integer
error:
type: string
required:
- status
- error
requestBody:
content:
application/json:
schema:
type: object
properties:
user:
type: object
properties:
email:
type: string
required:
- email
required:
- user
examples:
Password reset request:
summary: Valid password reset request
value:
user:
email: test@example.com
required: true
/register:
post:
summary: User Registration
tags:
- Basic Authentication
security: []
operationId: registerUser
parameters: []
description: 'Creates a new user account and returns the user data
'
responses:
'201':
description: User created and merged with dummy user
content:
application/json:
examples:
Successful registration:
value:
user:
id: 1
first_name: John
last_name: Doe
primary_email: new_user@howler.co.za
dummy?: false
schema:
type: object
properties:
user:
type: object
properties:
id:
type: integer
email:
type: string
first_name:
type: string
last_name:
type: string
primary_email:
type: string
dummy?:
type: boolean
required:
- id
- primary_email
- first_name
- last_name
- primary_email
- dummy?
required:
- user
'422':
description: Invalid registration data
content:
application/json:
examples:
Invalid registration data:
value:
status: 422
message: Registration failed.
errors:
email:
- is invalid
password:
- is too short (minimum is 8 characters)
password_confirmation:
- doesn't match Password
cellphone_number:
- is invalid
schema:
type: object
properties:
status:
type: integer
message:
type: string
errors:
type: object
additionalProperties:
type: array
items:
type: string
required:
- status
- message
- errors
requestBody:
content:
application/json:
schema:
type: object
properties:
user:
type: object
properties:
email:
type: string
password:
type: string
password_confirmation:
type: string
cellphone_number:
type: string
first_name:
type: string
last_name:
type: string
required:
- email
- password
- password_confirmation
- cellphone_number
- first_name
- last_name
required:
- user
examples:
Registration request:
summary: Valid registration request
value:
user:
email: new_user@howler.co.za
password: password123
password_confirmation: password123
required: true
components:
securitySchemes:
oauth2:
type: oauth2
description: OAuth2 authentication for third-party applications
flows:
authorizationCode:
authorizationUrl: /oauth/authorize
tokenUrl: /oauth/token
scopes:
public: Public scope
login: Login scope
ott: One-time token scope
bearer_header:
type: http
scheme: bearer
bearerFormat: oauth2
in: header
bearer_param:
type: apiKey
scheme: bearer
bearerFormat: oauth2
name: bearer_token
in: query
jwt_header:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT token obtained from basic authentication login
jwt_param:
type: apiKey
name: bearer_token
in: query
description: JWT token as query parameter (alternative to Authorization header)
basic_auth:
type: http
scheme: basic
description: Basic authentication with email and password
api_key:
type: apiKey
name: x-auth-token
in: header
description: API key authentication
bearer_auth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT token authentication