Access Token Swimlanes


  • Client - The front-end application, generally a Mobile App, but can be anything calling the REST API. (Can be tested via Postman, for example).
  • Auth0 - 3rd-party Authentication Service which is responsible for verifying the user is who they say they are and creating Access Tokens.
  • Clue Ride Server - Provides REST API which is protected by Access Tokens.
  • Access Token - Opaque and short-lived string issued by Auth0, carried by the Client session after authentication, and presented to the Clue Ride Server for each REST call. This Access Token can be taken to Auth0 to obtain details about the Client/User.
  • Session - A session is matched up with a particular principal and holds information specific to that principal: ID, Email Address, Game State, Badge details, Invitation Status, Image URL. The session expires at the time the Access Token expires, but Game State also plays a role in what information would be available.
  • In all cases, the Client talks to the Auth0 server to obtain a current opaque Access Token which is good for 12 hours (roughly the time-frame of an Outing). This diagram does not distinguish between a client that has
    • Just registered,
    • Just initiated a new session,
    • Renewed an Access Token from a Refresh Token
  • Auth0 uses an email address to connect the Client to a given Access Token.
  • The Client stores the Access Token for use with each request. The Access Token is presented as the Authorization: Bearer header in each request.
  • The ClueRide Server
    • Obtains the Client's Access Token from the request header,
    • Passes the Access Token to Auth0 to verify the token and to obtain:
      • Principal (Email Address)
      • Image URL (when available)
      • Expiration timestamp
    • Adds the Principal to the Session
    • Optionally updates the Member/User record with Image URL ??


  • When testing Auth in particular, supplying credentials is a challenge because the tokens need to match up with an account and that token needs to avoid expiration.
  • One option was to renew the token periodically.
  • A longer-term token is viable if it is only recognized within the test environment (configurable option that needs to be enabled within test?)

The design that has been implemented so far recognizes a configurable token that is recognized as a "test" token. The account to be mapped is also configurable.

Classes involved with Token Lookup

  • AuthenticationFilter - Called whenever a REST endpoint is invoked. Collaborates with AccessTokenService to retrieve Principal from Auth0.
  • AccessTokenService - Knows how to talk to Auth0 to present a token and receive User details — particularly the Principal which is generally an email address.

This has been expanded on the page Principal Into Session

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License