Honeygain.py

A python wrapper to interact with Honeygain's dashboard API.

Installation

$ pip install honeygain.py

Usage

import honeygain
from honeygain.schemas import UserProfile

EMAIL = 'mike@example.com'
PASS = 'V3ryZ3cUReP@sSw0rD'  # TODO: remove my totally real password

# log in...
client = honeygain.Client()
client.login(EMAIL, PASS)

# alternatively, if you already have a token:
# client.token = 'myAccessToken'

profile: UserProfile = client.get_profile()
print(f'--- Logged in as {profile.email} ---')
print(f'Created at:       {profile.created_at}')
print(f'JumpTask enabled: {profile.jumptask_mode}')
print(f'Active devices:   {profile.active_device_count} / {profile.total_device_count}')

A note about logging in

Due to the way this library works, running the above example will generate a new access token every time it's ran. Because of this, it is HEAVILY recommended that you store the access token somewhere and cache it so you do not have to call login() over and over.

Honeygain has set a very tight ratelimit on how often you can call the login endpoint, and they WILL prevent you from logging in again after a couple tries. When this happens, you are effectively locked out of your account and will have to try again the next day. That is, unless you have cached your access token like the smart person you are.

A very simple example to cache access tokens:

import honeygain

client = honeygain.Client()

# getting a stored access token
with open('token.txt', 'r') as file:
    client.token = file.read().strip()

# storing an access token after logging in
with open('token.txt', 'w+') as file:
    file.write(client.token)

Access tokens last for a very long time. If your token has expired, the API will tell you by raising a honeygain.HTTPException.

If you do get yourself locked out

Two options:

1. Accept defeat. Your code is bad and you should feel bad. Try again tomorrow, or in an hour if you're lucky.
2. If you are still logged in on a web browser:
   1. Open the honeygain dashboard
   2. Open devtools -> storage -> local storage
   3. Your token is listed under the JWT key for the dashboard domain.

Implemented endpoints

The base URL for all endpoints is https://dashboard.honeygain.com/api/v{version}. Version is 1 unless otherwise noted.

This library currently supports all endpoints of the Honeygain API as used by the official dashboard, and it is therefore able to get the same information and perform the same actions as you normally would through the dashboard.

Contributing

I realize that the way this library works right now might not be very intuitive at first - the issue is simply that Honeygain's (private!) API is not great. I've tried to introduce some improvements here and there, such as making property names more_pep8_compliant, but there's still a long way to go!

If you have any suggestions for the library, I'd be happy to accept pull requests. Please do create an issue before making large modifications though, so we can discuss the changes before you spend your entire afternoon on it :p