Managing the Authorization Lifecycle

Authorization Overview

In order to process transfers through Astra for an end-user in your application, you must collect an authorization. The resulting access_token becomes the authorization you use to make requests to Astra's API. The basic sequence and overview of each component are below.

Sequence

1. Pre-register the end-user's profile using a UserIntent
2. Present the Astra OAuth module for the end-user completed by clicking "Authorize" – this generates and returns a time-sensitive authorization code
3. Exchange that code for an access_token using the /oauth/token endpoint
4. Use the access_token as the authorization to make a request to get Accounts, create Routines, etc.

Please refer to the Authorization chapter to learn more.

Below is an overview of the key components to Authenticating a user:

Authorization Code (code):

• Function: an authorization code is generated when an end-user authorizes Astra by selecting the "Authorize" button via the OAuth module. The authorization code is then used in exchange for an access_token and refresh_token by way of the Authorization Endpoint POST /v1/oauth/token
• Expiration: several minutes
• What happens when an Authorization code expires? If the authorization code expires, the User will have to enter the OAuth module again to authorize and receive a new authorization code.

Access Token (access_token):

• Function: The authorization token for the User. This token authorizes your application to make requests based on actions taken by the end-user. An active access_token allows you to guide the User to perform actions such as setting up Routines and Transfers.
  • An access_token is used as the authorization for most of Astra's API endpoints.
  • Only one access_token is valid at a time.
  • An access_token as well as a refresh_token are generated in exchange for an Authorization code. This "exchange" occurs after the user has selected the "Authorize" button in the OAuth module.
• Expiration: 2 hours
• What happens when an Access token expires? If an access_token is created at 9am, it will expire at 11am. If an end-user were to attempt to create a transfer Routine at 12pm, they would need to re-authorize with Astra. When an access_token expires, it can automatically be refreshed using a refresh_token through the Refresh Authorization endpoint POST /v1/oauth/token

Refresh Token (refresh_token):

• Function: A refresh_token is granted with the associated accces_token and is used as a means to refresh both the access_token and refresh_token
  • A refresh_token can be re-used until it expires
  • A new refresh_token will be provided each time you call the endpoint to refresh an access_token
• Expiration: 10 days
• What happens when a Refresh token expires? If a refresh_token expires, the end-user will need to re-authorize Astra in your application through the OAuth module. To avoid this scenario, you can obtain a newrefresh_token with a recurring Task or cron job within its ten day lifespan

Token Management Recommendations

We recommend keeping track of the current active access_token for each user, and only refreshing the token (or generating a new access_token) when necessary. Refreshing the token before each request can lead to race conditions if there are near simultaneous competing requests.

Our recommended approach to token management:

• Keep track of the current active access_token per user along with the refresh_token and calculated expiration date.
• Use the current active access_token for all requests for a user.
• (Optional) Before using the access_token, you can check to see if the token is expired or near expiration.
• If you use the access_token and you receive an error (token expired), refresh the token and save for subsequent requests.
• (Optional) Lock getting/updating the access_token if it is being refreshed (ensuring the token is only refreshed once each time it is required).

Best Practices to Persist Authorization

Persisting the authorization of an end-user means that they only ever need to authorize with Astra once during their initial onboarding through your application. In addition, maintaining the health of an end-user’s tokens means that you have persistent access to their User records through Astra’s Dashboard and API, which contains their entire history with your client, including basic profile information, the cards they’ve connected, all of their routines and transfers, and more.

As a best practice, we recommend that you store both the access_token and refresh_token in your backend database. First, you need the refresh_token to refresh the authorization. Second, if you are not storing and updating these data items, you may encounter an issue where the wrong access_token is being utilized, but it in fact has expired or been revoked.

In your backend business logic, we recommend wrapping the request in a try/except method to complete the refresh and catch exceptions.

Additionally, we recommend that you obtain a new refresh_token for all of your existing tokens by way of a weekly recurring Task or cron job within the ten day lifespan of the refresh_token.