Introducing tokens-pls, a Web Application to Test OAuth2 Code Flows

Since I've been working a bit more with Micropub and IndieAuth, I've always had cases where I've wanted to test things locally, which requires retrieving an access token.

Fortunately, the OAuth2 Authorization Code grant is pretty straightforward, so doing this locally with i.e. curl is an OK process to go through, as well as using a guided tool such as Sebastiaan Andeweg's

However, with Proof of Key Code Exchange (PKCE) support now a requirement of IndieAuth, gimme-a-token isn't applicable, and the logic to run this locally with curl is a bit more complex, so I looked to script it.

I was thinking of creating a small script to go through the OAuth2 flow locally, with me copying-and-pasting the callback URL with granted authorization code, but thought I'd think a bit better about making this as easy as possible.

I've created a Sinatra app, tokens-pls for this, which provides an easy tool for going through the Authorization Code flow for a Public Client, which is currently hosted on Heroku at

The app allows you to either start the authorization flow using your profile URL (at which point it will discover your authorization_endpoint and token_endpoint automagically, or you can manually provide the endpoints. It is up-to-date with the IndieAuth spec (at time of writing) and uses PKCE to protect the authorization request.

After the authorization code is exchanged, tokens-pls will return in its JSON response the response from the token endpoint, and if an access_token, id_token or refresh_token are provided and can be parsed as a JSON Web Token, they will be populated in the response too:

  "token_endpoint_response": {
    "scope": "draft",
    "me": "",
    "access_token": "eyJ...",
    "expires_in": 604800,
    "token_type": "Bearer"
  "access_token_claims": {
    "aud": "",
    "sub": "",
    "auth_time": 1615033025,
    "scope": "draft",
    "iss": "",
    "exp": 1615637825,
    "token_type": "access_token",
    "iat": 1615033025,
    "client_id": "",
    "jti": "558c7f46-e605-4b1d-8097-f12ed8efef94"

Written by Jamie Tanna's profile image Jamie Tanna on , and last updated on .

Content for this article is shared under the terms of the Creative Commons Attribution Non Commercial Share Alike 4.0 International, and code is shared under the Apache License 2.0.

#indieauth #oauth2 #token-pls.

This post was filed under articles.

Interactions with this post

Interactions with this post

Below you can find the interactions that this page has had using WebMention.

Have you written a response to this post? Let me know the URL:

Do you not have a website set up with WebMention capabilities? You can use Comment Parade.