Managing the Authorization Lifecycle
The following guide presents information on the end-user authorization lifecycle and best practices for how to manage that authorization over time.
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
- 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 (code
):
code
):- Function: an authorization
code
is generated when an end-user authorizes Astra by selecting the "Authorize" button via the OAuth module. The authorizationcode
is then used in exchange for anaccess_token
andrefresh_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
):
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 arefresh_token
are generated in exchange for an Authorizationcode
. This "exchange" occurs after the user has selected the "Authorize" button in the OAuth module.
- An
- 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 anaccess_token
expires, it can automatically be refreshed using arefresh_token
through the Refresh Authorization endpoint POST /v1/oauth/token
Refresh Token (refresh_token
):
refresh_token
):- Function: A
refresh_token
is granted with the associatedaccces_token
and is used as a means to refresh both theaccess_token
andrefresh_token
- A
refresh_token
can be re-used until it expires and multiplerefresh_token
can be valid at one time - A new
refresh_token
will be provided each time you call the endpoint to refresh anaccess_token
- A
- 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
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
.
Updated 29 days ago