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 an access_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

  1. If the UserIntent status is approved, pending, retry, or document:
    1. Send them into the Collect Authorization Flow
    2. Include their UserIntent ID as a query string parameter
    3. 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
  2. If the UserIntent status is converted_to_user
    1. Do you have an active access_token for this User?
      1. If No
        1. Send them into the Collect Authorization Flow
        2. You must include the UserIntent ID
        3. 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
      2. If Yes
        1. Is the User status retry?
          1. Send them into the Retry flow
          2. Example URL: https://app.astra.finance/verify/personal?client_id=your_client_id&redirect_uri=your_redirect_uri
        2. Is the User status document?
          1. Send them into the Document flow
          2. Example URL: https://app.astra.finance/verify/document?client_id=your_client_id&redirect_uri=your_redirect_uri

If a UserIntent does not exist

  1. Create a UserIntent using the Astra API
  2. 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

I have a UserIntent with a status of converted_to_user and no access_token (no authorization), what do I do?

  1. Send the end-user into the Collect Authorization flow (see URL below)
  2. You must their UserIntent ID in the URL. Our system will detect their profile upon authentication.
  3. Do not include their User ID in the URL, as this isn’t an allowable query string parameter.
  4. 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.
  5. 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.
  6. 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 an access_token and refresh_token.
  7. 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?

  1. Send the end-user into the Collect Authorization flow (see URL below)
  2. You must include the UserIntent ID as a query string parameter in the URL
  3. 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 the retry screen after they authenticate. Provided that they are approved, they will ultimately reach the authorize screen.
  4. After the end-user authorizes, Astra will redirect back to your app with an authorization_code, which you can then exchange for an access_token and refresh_token.
  5. 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

I have a User with an access_token, but they are in retry status. What do I do?

  1. Send the end-user into the Retry flow, to verify their profile using the link below:
  2. https://app.astra.finance/verify/personal?client_id=your_client_id&redirect_uri=your_redirect_uri
  3. Note - if your User is a “business” user type, you’ll need to send them into the Business Verify flow below:
  4. 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?

  1. Send the end-user into the Document flow, to verify their profile using the link below:
  2. https://app.astra.finance/verify/document?client_id=your_client_id&redirect_uri=your_redirect_uri
  3. 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.