Local API


I’m using the backup one, along with the endpoints to read and write drivers and apps. Oddly enough, I hadn’t actually considered using the device control endpoints until this morning when a coworker asked me whether there was a local API.

And I would be using the integrated API to send/pull data to my (remote) SPLUNK server so I can continue to have dashboards like these.

1 Like

@patrick Do custom apps support any sort of push updates (e.g., websockets)? I noticed that the new Dashboard is polling every second or two rather than getting streaming updates.

Yes and no. We decided to go the poll route for dashboard, but you’ll notice that most of the responses are empty. We only send changed events in the poll.

We hope to have a more socket like functionality in the future, but we wanted to get dashboard out and not hold back for a socket method.

Sockets work great on a local lan but trying to make it work for remote connections via oauth2 endpoints poses some unique challenges we have to work out.

Apps can subscribe to events for capabilities and then can send those changes to any URL ala web hook. This requires a server to receive these. Since a browser isn’t a server, dashboard couldn’t use this method either.

Hmmmm so I think I have been doing local access to Hubitat wrong in HousePanel based on this thread. I don't use OAUTH at all on the Hubitat auth side of my app. Sounds like I should. @patrick can you confirm?

If true as I suspect, then my next question is does this flow follow the same logic as SmartThings? That is, do I have to call once to get a "code" and then again twice (after the GET callback returning the code) to request the auth token and endpoint? I couldn't find this explained anywhere. I assume one just replaces graph.api.smartthings.com with cloud.hubitat.com ?

If this is in some other thread please point me to it.

We actually have 2 oauth endpoints. There is the cloud one. which starts at https://oauth.cloud.hubitat.com/oauth/authorize

We also have a local endpoint you can use which starts at:
http://<HUB IP>/oauth/authorize

They follow the standard oauth2 flow, so you send client_id, response_type, redirect_uri and scope to the first url and go from there. (FYI response_type must be 'code' and scope must be 'app')

I have some example nodejs apps that use the local and cloud endpoints, but it uses the simple-oauth2 module so it might not be helpful if you are writing it in another language.

1 Like

Thanks - this is super helpul. I'm writing in PHP so I think I can take it from here. If the flow uses a two stage auth as usual then I am all set. Actually, one point of confusion is what oauth endpoint to use for retrieving endpoints. SmartThings uses a different one for that than they use for access_tokens. I assume for Hubitat I just build the endpoint using the access_token and can skip that third step?

Yes, we do use a 2 stage auth, it is just like the ST implementation.

In addtion, we do implement the endpoints url in both places: /apps/api/endpoints
you need to pass the Bearer token in the Authorization header with that call and it will give you the endpoints back.

One thing to keep in mind, we do not allow you to send the bearer token in the url as "access_token", you always have to use the Authorization header when sending the bearer token.

1 Like

Got it - just what I needed. Many thanks

Just to be sure, the access token is obtained using:


with parameters:

For the endpoints I know I have to use Bearer. Here is what my PHP code looks like for SmartThings. I assume this exact code will work for Hubitat with the hub $stweb variable set to a different value and change /api/smartapps/endpoints to /api/apps/endpoints
You said /apps/api/endpoints but I assume you meant the other order?

$host = $stweb . "/api/smartapps/endpoints";
$headertype = array("Authorization: Bearer " . $access_token);
$response = curl_call($host, $headertype);

when you call /oauth/token , you do not need to provide the scope, otherwise everything is correct in your list.

The code you are using for ST should work fine. and the url I mentioned earlier is correct: "/apps/api/endpoints"

would it be possible to have the event's data field in the /eventsocket stream?

There is no plan to make the event data available on that socket. In addition, that is an internal use endpoint so it is subject to change at any time.

ok, good to know. I'm currently forwarding from within an app and works nicely. Having those in a websocket would have allowed to have less load on the hub but will work anyway. I understand it is internal and I by no means request any guarantee on it :wink:

Are any of these endpoints documented. My hub was in a 500 error right now and was looking for this command and could not find it handy anywhere. I ended up pulling the plug.

Not at this time. These are internal methods and probably won't be documented vs improving the ui to be able to handle things better.

1 Like

Ok just making sure - thought there might be a simple a url to enter in the browser or such.
Thanks for the response...

Not sure what you are asking for? If your hub is at a hard stop and every page is loading a 500 error, grabbing a database backup would have that issue in it. The hub stores 5 days worth of backups.

Are you looking to restore a specific day / database? A reboot is meant to fix a database issue on startup.

If you just have an app throwing a 500 error, you can always go into settings, backup / restore and restore the last known good db.

Honestly I was interested in a remote command to tell the hub to reboot.

I was playing with some code and caused some kind of meltdown - I could access the location page but everything else was returning a 500 error.

My thought was maybe if there was a command available I could tell the hub to reboot rather than pulling the plug. There is a good chance this command would fail as well I guess. I just did not know without being able to try.

I though I had seen talk of some sort of endpoint being available to do this sort of thing. Not a big deal, just figured I would ask in order to be armed for next time.

Some sort of remote reboot method could be beneficial in some cases?

Edit: I saved the code in case anyone wants to try it. - Past logs showed a cool error I had never seen before.


Check out this thread. You can remotely reboot the hub in a variety of ways but the web service would need to be running.

1 Like