⚠️ Important Access Tokens Updates - effective March 4, 2025

[rectifyer]

⚠️ Starting on March 4, 2025, an OAuth access_token will expire in 24 hours, instead of 3 months.

This is currently a proposal. We will also email all API developers with this info once we have it finalized.

Why are we reducing the expiration?

3 months is a long time and is a potential security risk if the access_token gets intercepted. We're instead going with a much lower 24 hours and relying on apps to automatically use the refresh_token more often to obtain a new access_token.

Do I need to update my app?

Probably not, since you should already be handling expired an access_token and refreshing it automatically. If you're hard coding a refresh interval, we suggest making that check dynamic and based on the expires_in value instead. If you aren't doing this, check out the Trakt API docs.

What about existing access tokens?

They should continue to work up until their expiration date. At that time, your app needs to refresh it and get a new access_token, then use the expires_in value so your app can dynamically handle when to refresh.

---

Please let us know your feedback on this change and if your app will be impacted. It's possible there are use cases we haven't considered, but in general any OAuth library should be able to auto refresh tokens no matter the expiration set on them.

[michaldrabik]

I'd say 2 hours is a bit harsh? I think even PayPal has it set for like 10 hours or so.

Anyway it would be nice to have a longer time to react with such changes. I'm talking for like 1 month+.

11 Feb is in 5 days. If someone does need to react and make changes in their code (for example iOS app) it can take 5 days to let alone pass the apple review. Not even counting update propagation time across all users devices which takes many more days.

I do not think there is remote chance this change information will reach all interested parties anyway in the first place.

[michaldrabik]

@rectifyer It was not the most optimal way but it has been refreshed manually every 30 days (as token lifetime was 90 days). I think 90 days was there since the beginning of Trakt API.

Never had a chance to update it until today ofc as everything was just fine for years and refresh token endpoint was only called once per 30 days. Now it will be called much more often naturally.

[kevincador]

I'm doing exactly the same. When the user opens the app, before doing anything else, I check for the expiration date and I'm refreshing the token after 30 days or more. Then do everything else.

With a 2 hours expiry, I'll have to check before each API call, not a big deal. One thing that may be tricky is that I could make multiple API call in parallel that would end up refreshing the token on two different thread making subsequent API calls fail. I'll need to take that into account.

[rectifyer]

Thanks for the feedback and yes that makes sense to need more time for app reviews along with a bit longer of a token expiration. I will talk with the team and figure out a plan and update this thread when I have that info. I am also going to email all API developers the info once we settle on the specifics.

[michaldrabik]

@rectifyer Thanks. At this moment should we haste with updates or can you confirm it will not go live on 11th Feb?

[rectifyer]

@michaldrabik We are still finalizing, but it looks like March 4 will be the new date and the expiration will be 24 hours. I would still work on any app updates ASAP just to get the process started. I'd also recommend using the expires_in dynamic value to be future proof.

[kevincador]

I'd also like to have more time to test — and more than probably have fixes for — this 😅

And, if possible, could you make that change on Staging? Maybe even set something like 20 minutes on Staging so we can test in different conditions (app coming back from background after token expiration, app is in foreground while the token expires, background processes, widgets 😬,...) faster.

[rectifyer]

Good feedback, thank you. I'm particularly interested how this affects widgets in iOS.

[kevincador]

For my widget, when displaying a TV Show, I'm calling the progress API to present the next episode to watch. It is a call that needs authentication and so far, because widgets are different by nature, I assumed the token was alive when I retrieve it from the secured/shared storage. I can't make that assumption anymore.

I already have a fallback for this tho, the widget will display the TV Show if it fails to get the progress for the user. I may just let this work like this to avoid refreshing the token and create other problems there.

I guess the biggest issue is that the widget runs in an app extension, not the main app. And it is possible that both the app extension and the app are running at the same time (this also applies to background refresh). Plus, the app could make parallel calls and ask for a refreshed token at the same time. The token may be updated at the sam-ish time by multiple processes and threads, with will at some point fail.

Also, widgets and background refresh may be killed (the probability is higher than for the app itself) before the token is stored. Meaning, we'd have asked for a new token that couldn't be stored and the one stored (the old one) would be invalid for you (right?). That's why I think a 24h token would be better (assuming the app is opened at least once a day, avoiding refresh in widgets and background refresh).

[tysonkerridge]

I had the same thoughts regarding widgets, which are buggy by nature at the best of times I think we can all agree! I don't know what the sweet spot will be but 24 hours is a decent start compared to 2 which would almost certainly kill authenticated widgets unless there's some other workaround I'm unaware of - eg. any background refresh is spotty/can be disabled by users and would cause widgets to need some intermediate state if it waits too long; and trying to have a separate oauth token in the widget realm would cause either the user to need to authenticate twice, and still have issues due to each widget potentially running in a complete different process; which all becomes quite complex. Honestly unsure how other apps handle it otherwise.

[tysonkerridge]

Btw, I would definitely suggest avoid any chance of refresh happening in parallel because it will definitely cause you pain 😛! I have a helper class that offers the retrieval of the access token and refreshes if needed and stores completions for things that all call at the same time to get the callback once the refresh is complete and updated etc. I'd love to know what the best way to handle that is when applying to almost every remote call that needs an access token as right now I have to add a call to that helper before any authenticated remote call which adds a lot of bloat but can't think of any good solution and I've done it that way for years.

[kevincador]

Yeah, widgets 😅

Background refresh comes with the same type of issues. I've seen background refresh process still run while the main app was in foreground. They also get killed for no reason because the system needs to kill something. Also file operations are pretty much always unreliable at best.

What I've seen in the past that fixes those kind of problems:

• tokens with a validity of 3 months 😏
• refresh tokens that do not rotates and have an infinite validity
  This obviously has a security cost.

I've also seen worst, like session token that rotates with each and every API call. But at some point, it's a balance between security and user frustration.

One other problem with this inter-process, multi-thread or app being killed before the new token (and refresh token) is stored is: usually, if someone uses an old refresh token, the server assumes the token has been compromised and invalidate both the request for a new token and the valid token. This is because the server can't know if the latest token is used by the legit app or the "attacker".

Anyway, I will avoid refreshing the token in any of my app extensions to avoid the inter-process locking/communication stuff. I'm using a library to build all requests and I already have a hook in place that runs before the request is complete that can additionally check the validity and refresh the token if needed before the request is sent. I just need to make sure everything is thread-safe there and I hope the performance hit won't be too high (shouldn't).

I also need to check how this will work for retries after a rate limit is hit. I think I need to make sure the retries also check for the token validity. It is also possible I worry too much 🤣

[rectifyer]

Here is the email we're planning to send. It has the same info in the main post in this discussion. Please let me know if there is additional info that should be added to make this more clear or help out with any app updates.

[kevincador]

Perfect 🙏

[marcus-crane]

Heya, I just received the token update email.

I'm using Trakt for a side project and just had a recurring quarterly calendar event to manually refresh my access token so it's a good incentive to finally automate that 😉

I was wondering if the refresh tokens are infinite or if a new one is served with every new access token?

[marcus-crane]

From a quick skim of the docs, the access token lifespan is mentioned 5 different times but the refresh token lifespan is never explicitly mentioned

[tysonkerridge]

You get back a new refresh token when it's used. If you try to refresh with the same token you'll get back an error. related

I'm unsure how long the refresh token lasts unused - I assume it is unlimited (or a very long expiry) but @rectifyer would have to confirm that part.

[marcus-crane]

Thanks!

[linaspurinis]

Currently, we can refresh tokens in the background without impacting the user. However, with the new changes, there is no longer enough time for this. If a user logs in daily, the token will likely be expired every time, and there are two options:
1. Make the user wait for the token to refresh, but what if the endpoint is busy or down?
2. Allow the user to log in, but limit all actions related to Trakt until the token is refreshed in the background.

This approach would require significantly more work compared to the current implementation.

[rectifyer]

The refresh_token won't expire in 24 hours (I'll need to verify what the expiration actually is). I'm unclear what would need to change with your current logic?

[linaspurinis]

A lot, actually. At the moment, I don’t check expiration in the frontend at all—only in the backend. With the previous 90-day grace period, handling it in the background was simple.
Now, with a 24-hour token expiration, I’ll need to implement token refresh in the frontend. I’ll also have to add row locking to prevent multiple processes from refreshing the token simultaneously. And what if the endpoint is unavailable? That’s another potential issue.
This is probably not everything—there are likely more challenges I haven’t considered yet.

[jonathanreed82]

How is this going to affect using Apple's Shortcuts app to log films? I currently have a shortcut with the token manually pasted into a text field which then passes it through to the rest of the shortcut as a variable. I have a reminder to refresh this every 3 months but I can't do this every time I want to log a movie. This is really important to me as I use a shortcut from Letterboxd to log a film I've just reviewed on the platform.

I'm guessing this just completely kills my shortcut?

[tysonkerridge]

If you have the refresh token and expiry values too you could theoretically refresh if expired and then make the call (internally within the shortcut)

[kevincador]

I've never done this with a Shortcut and I wouldn't know where to start but I'm giving my 2 cents anyway 😉

1. From Apple Support

OAuth 2, a system of authentication that requires a user to manually enter their username and password on a login page, is currently not supported.

That said, my suggestion would be to check if something can't be done with the Device Authentication flow. I guess you can display the code to the user and have a button (assuming polling is not possible with Shortcuts) to fetch the Access and Refresh Token.

2. Once you have a Refresh Token, you are able to ask for a new Access and Refresh Token with one api call, use the latest Access Token and store the Refresh Token for later use. You should be able to dump the JSON response with the Tokens (and validity) to a file (on the user's iCloud Drive) and retrieve it with Shortcuts (I'm not saying it's trivial 😅 but possible). Warning tho: tokens should be stored securely, always, I'm pretty sure you don't have access to the Keychain or another secured data pool via Shortcuts. I'm also not saying you should ask for a new token each time you make an API call to Trakt (please don't), I'm saying it should be possible to implement a proper OAuth flow.

Hope this helps.

[jonathanreed82]

Yeah, this is maybe beyond my abilities though I may read up on it and see if I can get it to work. Seems like it would very very difficult though.

Thanks for your help. 😊

[kevincador]

You may want to take a look at this #429 (comment) 🤗

[kevincador]

I'm currently testing a new implementation in Rippple that seem to work okay 👌

I've been doing a lot of testing this weekend. It took several attempts like:

• checking the validity of the token before a request was created,
• checking the validity just before the request was sent.

Those two ended up with a lot of headaches because one was synchronous, the other asynchronous and both were at some time deadlocking everything or breaking the refresh token rotation. As I said above, the hard part is multi-threads, multi-processes, everything all the time all at once. Also taking into account relying on the stability of the internet connection, the backend, the local&secured storage,... is also not always 100% possible.

Because my Widget can't refresh the token (for reasons explained above and more), my final strategy is to refresh the token when the user "opens" the app and after only 1h after the creation date (or less if the validity one day comes lower than 1h but I hope not because it will kill the Widget for sure).
This is working for me for 2 reasons:

1. the token is always refreshed on the same thread and process + the code path is known making testing easier... still time-consuming but better,
2. it always gives my Widget a ~24h time-to-live + I have fallbacks until the app is re-opened if the access-token becomes invalid

Hope the 1h refresh is okay from Trakt point of view. My guess is, yes, since it won't practically be every 1h AND it is close to the 2h actual validity that was the first plan 😊