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:
- 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.
- 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
- 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
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
Updated 29 days ago