Guide to Astra's SDK
A UserIntent manages the lifecycle of the creation of a User, before that User has been fully created. A User is created when an end-user authenticates through Astra's SDK. When an end-user authorizes Astra, your client will ultimately end up with an access_token
, which grants your application the ability to make money movements on their behalf.
When a UserIntent is submitted to Astra, a UserIntent status is returned. When an end-user authenticates via Astra, their User profile is created, which inherits the status of their UserIntent. In order to successfully onboard your end-users, you must know the following three things:
- Does a UserIntent for this end-user exist?
- If yes, what is the status of their UserIntent?
- If their UserIntent status is
converted_to_user
, do they have anaccess_token
?
The following guide is meant to address questions regarding how to manage Users and UserIntents of varying statuses relative to the different OAuth flows our SDK provides.
Generally, we recommend that once a User is logged into your application, you handle their profile in the following manner:
If you have already created a UserIntent in Astra
- If the UserIntent status is
approved
,pending
,retry
, ordocument
:- Send them into the Collect Authorization Flow
- Include their UserIntent ID as a query string parameter
- Example URL:
https://app.astra.finance/login/oauth/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri&response_type=code&user_intent_id=your_user_intent_id&phone=your_10_digit_phone_number&phone_read_only=true
- If the UserIntent status is
converted_to_user
, or if the User is a Business User.- Do you have an active
access_token
for this User?- If No
- Send them into the Collect Authorization Flow
- Include the UserID
- Example URL:
https://app.astra.finance/login/oauth/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri&response_type=code&user_id=your_user_id&phone=your_10_digit_phone_number&phone_read_only=true
- If No
- Do you have an active
If a UserIntent does not exist
- Create a UserIntent using the Astra API
- An end-user must pass our security checks and have an
approved
status in order to use our services and be allowed on the Platform
FAQ
My User doesn’t have an access_token
or their access_token
has expired
access_token
or their access_token
has expiredI have a UserIntent with a status of converted_to_user
and no access_token
(no authorization), what do I do?
- Send the end-user into the Collect Authorization flow (see URL below)
- You must include their User ID in the URL. Our system will detect their profile upon authentication.
- Our SDK will handle the status of the User profile and guide the end-user through the appropriate screens (upload document or retry). The end-user will ultimately reach the authorize screen.
- After the end-user authorizes, Astra will redirect the end-user back to your app with an
authorization_code
, which you can then exchange for anaccess_token
andrefresh_token
. - Collect Authorization URL:
https://app.astra.finance/login/oauth/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri&response_type=code&user_intent_id=your_user_intent_id
I have a UserIntent with a status that is approved
, pending
, retry
, or document
, and there is no User record. I also don’t have an access_token
for this User. What do I do?
- Send the end-user into the Collect Authorization flow (see URL below)
- You must include the UserIntent ID as a query string parameter in the URL
- Note do not include the UserIntent ID as a query string parameter in the URL if a phone change request has been successfully processed for the existing User record.
- Our SDK will handle the status of the User profile and guide the end-user through the appropriate screens. For example, if the UserIntent status is
retry
, our SDK will guide the end-user to theretry
screen after they authenticate. Provided that they areapproved
, they will ultimately reach the authorize screen. - After the end-user authorizes, Astra will redirect back to your app with an
authorization_code
, which you can then exchange for anaccess_token
andrefresh_token
. - Collect Authorization URL:
https://app.astra.finance/login/oauth/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri&response_type=code&user_intent_id=your_user_intent_id
My User has an access_token
, but they aren’t approved
access_token
, but they aren’t approved
I have a User with an access_token
, but they are in retry
status. What do I do?
- Send the end-user into the Retry flow, to verify their profile using the link below:
https://app.astra.finance/verify/personal?client_id=your_client_id&redirect_uri=your_redirect_uri
I have a User with an access_token
, but they are in document
status. What do I do?
- Send the end-user into the Document flow, to verify their profile using the link below:
https://app.astra.finance/verify/document?client_id=your_client_id&redirect_uri=your_redirect_uri
- Note - this is the same URL for both Personal and Business user types.
I have a User with an access_token
, but they are in rejected
status. What do I do?
If the end-user is rejected
, this means that they did not pass Astra’s KYC and security checks. They are prohibited from using our services. If you feel that this was in error, please contact Astra support.
I have a User with an access_token
, but they are in suspended
status. What do I do?
If the end-user is suspended
, this means that Astra explicitly removed the User from the Astra platform for suspicious or fraudulent activity. If you feel that this was in error, please contact Astra support.
Additional Notes
Suggested User Experience for Initializing Astra’s SDK
It’s up to your team to determine how Astra’s SDK is initialized in your application. You may choose to implement triggers based on explicit User interactions, such as a User selecting a “Fund My Account” or “Add New Debit Card” button. Alternatively, you could automatically launch our SDK without explicit User interaction. For example, once the User is logged into your application, you could choose to automatically launch the Collect Authorization flow if you detect that the User’s access_token has expired. Or you could automatically send the User into the Retry flow if you detect that their User status is retry
.
Updated 3 months ago