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
- If the UserIntent status is
converted_to_user
- Do you have an active
access_token
for this User?- If No
- Send them into the Collect Authorization Flow
- You must include the UserIntent ID
- 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
- If Yes
- Is the User status
retry
?- Send them into the Retry flow
- Example URL:
https://app.astra.finance/verify/personal?client_id=your_client_id&redirect_uri=your_redirect_uri
- Is the User status
document
?- Send them into the Document flow
- Example URL:
https://app.astra.finance/verify/document?client_id=your_client_id&redirect_uri=your_redirect_uri
- Is the User status
- 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 their UserIntent ID in the URL. Our system will detect their profile upon authentication.
- Do not include their User ID in the URL, as this isn’t an allowable query string parameter.
- Do not substitute the end-users UserIntent ID with their User ID. Our system will be unable to locate the User’s profile since there will be no such UserIntent record with that ID.
- 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
- 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
- Note - if your User is a “business” user type, you’ll need to send them into the Business Verify flow below:
https://app.astra.finance/verify/business?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
Race Condition with UserIntent Statuses
Depending on when you send Astra a UserIntent and when you send your end-user into our SDK, you may run up against a race condition, where Astra hasn’t yet returned an updated UserIntent status, and the status is still pending
. A User will ultimately be guided from our Authentication flow to our Authorization flow. This is one way in which you can end up with end-users who have UserIntent statuses that are converted_to_user
, and User statuses that are retry
or document
.
To avoid running up against a race condition, we recommend sending Astra a UserIntent the moment your application has gathered the necessary information. We also recommend that if you have existing Users, you batch process all their UserIntents at once, so that their statuses are known before the User ever enters the Astra SDK.
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
.