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

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.