Why?

Previously, when the user completes the authentication process with Recess and we redirect to your callback URI, we send you a token that directly contains the user’s data. This isn’t ideal — directly embedding user data in token increases exposure if token is intercepted, lack of standardization, and complicated expiry management.

With this change, we will not only give you access to up-to-date user data, but it also unblocks our ability to give you fun API endpoints in the future, for example:

• securely distinguish between verified adults and kids (!)
• securely querying social graphs between users
• checking for registration status of specific courses
• posting to activity feed as an application or a developer
• distributing your app as an embedded, integrated experience on the Recess platform
• …

More on these APIs and abilities soon. But first, proper authentication token exchange!

How?

We will soon become RFC-6749 / OAuth 2.0 compliant. That means instead of giving you a JWT that contains the user’s token directly, you will now follow the following process to retrieve the user object from us:

1. User clicks “Log in with Recess” on your site (unchanged)
2. User completes authentication on Recess (unchanged)
3. User is redirected to your callback URI, which now has a querystring code=... — this is the Authorization Code.
4. Your server will then exchange the Authorization Code with our API server, in return for an Access Token and Refresh Token. Store both.
5. You now have a user-scoped credential. To access the user’s data, make an API request to Recess with the Access Token.
6. When making future requests, if your Access Token becomes expired, you can use the Refresh Token to exchange for a new set of Access Token and Refresh Token.

Timeline

• December 2024 — The OAuth 2.0 endpoint will be available in production by December. We’ll make an announcement with detailed APIs when it’s ready. The old endpoint will continue to work.