API app callback tokens

I’m trying to figure out subscription callback authentication tokens.

I see references to “5 minute disposable tokens” scattered across the forum, however I cannot verify whether it is documented or working.

This documentation implies that a token should be returned in eventData.authToken, however it does not seem to be the case. At least not in API_ONLY kind of app.

When the below callback method is called, the context is not populated.

SmartApp.subscribedDeviceLifecycleEventHandler(name: string, callback: (context: SmartAppContext, eventData: AppEvent.DeviceLifecycleEvent, eventTime?: string)

Are callback tokens reserved only for automations?

1 Like

Hi, @625alex!

That expiration time is only for the SmartApps installed in the ST app and the NodeJS SDK refreshes automatically the Access Token when a request to the API is made. This requires saving the SmartApp context and including the Client ID and Client Secret` in the SmartApp definition.
For OAuth integrations, the expiration time of the Access Token is 24hrs.

This is also true for the SmartApps installed through the ST app and this is because they handle the request and refresh of the Access Token, unlike the ones created in an OAuth integration which only receive the stored context.

That’s why, when we receive the events in the OAuth application (in the Target URL), we call handleOAuthCallback because it identifies the stored context (installedAppId, accessToken, refreshToken, etc.).

The SmartApp SDK indicates that the context should be instantiated.

SmartApp.subscribedDeviceEventHandler(name: string, callback: (context: SmartAppContext, deviceEvent: AppEvent.DeviceEvent, eventTime?: string) => HandlerResponse): SmartApp

However the contract is not met where context.api shoud be ‘An instance of the SmartThings core API instantiated with the access token for the installed app instance.’

I think this is due to the difference in event handling of oAuth and SmartApp apps. The documentation does not make this distinction and the SDK does not automatically initialize the context for oAuth callbacks.

This property is used to make requests from the SmartApp to the API using the SmartApp Token which is handled automatically by the SDK in the traditional implementation of a SmartApp.

Yes, there are differences in the implementation and it’s due to the total control on our side (as OAuth integrators) of all the requests made to the API and the Access Tokens. In this kind of integration, not only one user will interact but a lot of them, which means different instances of installedApp will be generated and this needs better control.

Thank you for your feedback, I already shared your comments about the OAuth documentation improvement regarding the usage of SmartApps there.