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&phone=your_10_digit_phone_number&phone_read_only=true
  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
          1. 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.
        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&phone=your_10_digit_phone_number&phone_read_only=true

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
    1. 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.
  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

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.