How to use the Homebox API

[nodecentral]

First Check

• This is not a feature request
• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue and didn't find it.
• I searched the documentation, with the integrated search.
• I already read the docs and didn't find an answer.

Homebox Version

Version: v0.9.1 ~ Build: d3b6c93

What is the issue you are experiencing?

I’m trying to work out the API, using the guide on https://redocly.github.io/redoc/?url=https://hay-kot.github.io/homebox/api/openapi-2.0.json

A couple of immediate things came up, which make me think I must be missing something obvious.

1. How do I obtain my bearer ID ?
2. If I want to test a few GET requests e.g 192.168.102.134:3100/v1/items/{id} via the browser, it returns a 404 error

How can the maintainer reproduce the issue?

I expect this is working fine for the maintainer, it’s more an issue with me..

What would help immensely would be to share some real world/specific examples, such as a curl command to obtain my bearer ID, and then another curl command to GET an item and to POST an item.

Deployment

Other

Deployment Details

Docker QNAP

[proffalken]

On the swagger docs, click "try this out" for the login call, and then input your username and password.

It will return both the curl call and an active bearer token.

You can then put this in the authentication token box at the top of the swagger UI and continue to use the UI to get the API calls etc.

[nodecentral]

Hi @proffalken , sorry where do I find the swagger docs , as the Homebox documentation (https://hay-kot.github.io/homebox/) API link just points to the ReDoc location ?

[proffalken]

@nodecentral if you're already running homebox, then you can find them locally at http://yourhomeboxURL/swagger/index.html

[nodecentral]

Thanks @proffalken , that help, and i’,m able to GET a few things back, where i’m struggling is with the login, to get my token. I’ve tried various ways, but can’t get the swagger Login api call to work? Example below..

 curl -X 'POST'   'http://192.168.102.134:3100/api/v1/users/login'   -H 'accept: application/json'   -H 'Content-Type: application/x-www-form-urlencoded'   -d '{"password":"mypassword","stayLoggedIn":true,"username":"myname"}'

Which returns the following..

{"error":"Validation Error","fields":{"password":"username or password is empty","username":"username or password is empty"}}[

[icsy7867]

Thanks @proffalken , that help, and i’,m able to GET a few things back, where i’m struggling is with the login, to get my token. I’ve tried various ways, but can’t get the swagger Login api call to work? Example below..

 curl -X 'POST'   'http://192.168.102.134:3100/api/v1/users/login'   -H 'accept: application/json'   -H 'Content-Type: application/x-www-form-urlencoded'   -d '{"password":"mypassword","stayLoggedIn":true,"username":"myname"}'

Which returns the following..

{"error":"Validation Error","fields":{"password":"username or password is empty","username":"username or password is empty"}}[

Just copy pasted this straight from the login section of the swagger.

curl -X 'POST' \
  'https://homebox.myserver.com/api/v1/users/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=XXXXXXX&password=YYYYYYYY

It's URL encoded, so things like symbols will use these values.

[proffalken]

@nodecentral - as @icsy7867 has demonstrated, the data needs to be in query-string format, not JSON.

Here's an example in python of how you might log in:

# Get the username/password from the environment
username = os.getenv("INVENTORY_USER")
password = os.getenv("INVENTORY_PASSWORD")
auth_uri = "api/v1/users/login"
inventory_host = "https://myhomeboxinstall/"
asset_search_uri = api/v1/items
# Setup the default headers that will be used for all API calls
headers = {}
headers["accept"] = "application/json"
headers["Content-Type"] = "application/x-www-form-urlencoded"

# Get the bearer Token we will need
print(f"Obtaining bearer token from {inventory_host}/{auth_uri}")
# Set the parameters
params = {}
params["username"] = username
params["password"] = password
# Make the request using the headers and params
bearer_request = requests.post(f"{inventory_host}/{auth_uri}", data=params, headers=headers)
# Get the token from the field
bearer_token = bearer_request.json()["token"]
# Add it to the common headers
headers["Authorization"] = f"{bearer_token}"
# Remove the username and password from the parameters
params.pop("username")
params.pop("password")

# Create a function that calls the API and returns the results
def search(item_name):
    items = []
    params["q"] = item_name
    with tracer.start_as_current_span("search_items") as search_span:
        item_results = requests.get(f"{inventory_host}/{asset_search_uri}", params=params, headers=headers)
        item_json = item_results.json()

[nodecentral]

Hi,

I’m not proficient in python, all I’m doing is following the swagger ‘login’ guidance, but it always fails , yet my username/password are correct ?

Does the curl example work for you ?

[proffalken]

Yes, the current CURL example works for me, and it's what I used to construct the python code above.

I note that your screenshot says "500 Internal Server Error" rather than the expected "401 Unauthorized" that you'd usually get if the username/password was incorrect.

What do the logs say?

[nodecentral]

looking in the logs I get the same sort of message..

15/04/2023 23:55:46
10:55PM INF ../go/src/app/internal/web/mid/logger.go:25 > request received method=POST path=/api/v1/users/login rid=4b89bd2673f8/bOPglU27Mr-001070
15/04/2023 23:55:46
10:55PM ERR ../go/src/app/internal/web/mid/errors.go:31 > ERROR occurred error="authentication failed" req_id=4b89bd2673f8/bOPglU27Mr-001070

But from what i can tell, I’m using the correct details ?

[hay-kot]

I note that your screenshot says "500 Internal Server Error" rather than the expected "401 Unauthorized" that you'd usually get if the username/password was incorrect.

FYI, the authentication endpoint will return 500 on any error case which is a common security practice.

Are you sure your username and password are correct?

I've tried the swagger documentation on the demo site and it works correctly

The Login endpoint accepts both JSON and Form Data and parses based on the Content-Type provided in the request. Both of these example should work

curl -X 'POST' \
  'https://homebox.fly.dev/api/v1/users/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=demo%40example.com&password=demo'

curl -X 'POST' \
  'https://homebox.fly.dev/api/v1/users/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "password": "demo",
  "stayLoggedIn": true,
  "username": "demo@example.com"
}'

[nodecentral]

Thanks @hay-kot , I noticed you have used an email address for your username, I had tried that initially and it didn’t work, and then I tried my registered (user) name. Will try email again and report back

[nodecentral]

Ok, I think I can see where I was going wrong now.

Initially I was taking the curl command example exactly as swagger was providing as its example..

.. and then updating that with my username and password, shared in earlier post, but added below too.

curl -X 'POST' \
  'http://192.168.102.134:3100/api/v1/users/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d '{"password":"mypassword","stayLoggedIn":true,"username":"myusername@hotmail.com"}'

Which did not work, and was giving me the following error.

{"error":"Validation Error","fields":{"password":"username or password is empty","username":"username or password is empty"}}

It was then from there, where I started to freestyle a bit trying to work out what I was doing wrong, hence the post :-)

So to sum up, the examples @hay-kot provided both work - but they do differ from the swagger example above (or at least my interpretation of them) - in that for their first example - swagger has -d is wrapped in curly brackets { } , which @hay-kot doesn’t, and then for the second, swagger has the content type set as application/x-www-form-urlencoded yet it needs to be changed to application/json..

All this is likely down to how i was treating Swagger, and not reading between the lines/interpreting the command requirements correctly, but I’ve got there in the end - thanks again .. 👍