The following guide presents information on the end-user authorization lifecycle and best practices for how to manage that authorization over time.
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.
- Pre-register the end-user's profile using a UserIntent (optional)
- Present the Astra OAuth module for the end-user completed by clicking "Authorize" – this generates and returns a time-sensitive authorization code
- Exchange that code for an access_token using the /oauth/token endpoint
- 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 (
- Function: an authorization
codeis generated when an end-user authorizes Astra by selecting the "Authorize" button via the OAuth module. The authorization
codeis then used in exchange for an
refresh_tokenby way of the Authorization Endpoint POST /v1/oauth/token
- Expiration: several minutes
- What happens when an Authorization code expires? If the authorization
codeexpires, the User will have to enter the OAuth module again to authorize and receive a new authorization code.
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_tokenallows you to guide the User to perform actions such as setting up Routines and Transfers.
access_tokenis used as the authorization for most of Astra's API endpoints.
- Only one
access_tokenis valid at a time.
access_tokenas well as a
refresh_tokenare 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_tokenis 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_tokenexpires, it can automatically be refreshed using a
refresh_tokenthrough the Refresh Authorization endpoint POST /v1/oauth/token
Refresh Token (
- Function: A
refresh_tokenis granted with the associated
accces_tokenand is used as a means to refresh both the
refresh_tokencan be re-used until it expires and multiple
refresh_tokencan be valid at one time
- A new
refresh_tokenwill be provided each time you call the endpoint to refresh an
- Expiration: 10 days
- What happens when a Refresh token expires? If a
refresh_tokenexpires, 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_tokenwith 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
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