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 (optional)
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 and multiple refresh_token can be valid at one time
  • 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 new refresh_token with a recurring Task or cron job within its ten day lifespan

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.

After the first access_token is generated, we recommend that you attempt to refresh the access_token before subsequent API requests. 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.