API Only Authorization

Overview

Authorization defines the relationship between your Client and your User when interfacing with the Astra Platform. Through Authorization, a User is granting your Client permission to process payments through Astra’s API on their behalf. Authorization also grants your application access to the End-User’s Astra data.

Astra supports an API-only Authorization feature for enterprise customers that streamlines User onboarding flows and enables Clients to completely control the User Interface and Experience. The following guide outlines five easy steps to gain access to API-only Authorization.

Step 01: Create a Client

Sign up and create an Astra Sandbox Client here: https://dashboard-sandbox.astra.finance/

Step 02: Enable Client for Trusted Authentication

Provided that your program is eligible and approved for Trusted Authentication, your designated Astra Account Manager will configure and enable your Client for Trusted Authentication. Authentication is the process of Astra correlating a User’s phone number to their identity through 2FA phone verification.

If your application Authenticates Users through 2FA phone verification, then you are eligible for Trusted Authentication, providing a minimal, streamlined onboarding experience. If a User has Authenticated with your Client in the last 30 days, Astra will “trust” this Authentication and allow the User to bypass the Authentication step in our SDK.

📘

Astra will require documentation from your business, detailing how you conduct
Authentication. Please read Astra’s Guide to Trusted Authentication guide for additional details

Step 03: Create User Profile

The first step of onboarding a User to Astra’s Platform entails a high-resolution security
assessment, which starts with the submission of a UserIntent.

A UserIntent is a collection of personally identifiable information (PII) for a customer profile that you intend to create in Astra. This information is used to run a security and background check on the User, which includes standard KYC, and to provision a User profile in our system with specific capabilities.

The purpose of this high-resolution security check is to determine if someone really is who they say they are and prevent fraudulent profiles from accessing your payments program. The result of this security check and KYC ultimately determines if the User is permitted to use Astra’s services.

The successful creation of a UserIntent will result in a UserIntent ID

Step 04: Obtain Session Token

Call Astra’s POST Generate Partner Identity Verification endpoint to obtain a session_token for the User. Provide the UserIntent ID created from Step 03. This Session Token is required for Authorizing Users in Step 05. See example payload and response below:

POST /v1/partner/identity/verification
Headers: \{
"Content-Type": "application/json", "Accept": "application/json", "Authorization": "Basic \*\*\*\*",
}
\{
"provider": "\<Client Name>", "provider\_data": \{
"customer\_id": "123456" },
"client\_id": "client\_123456",
"user\_id": "user\_123456",
"user\_intent\_id": "user\_intent\_123456" "business\_profile\_id": "busines\_profile\_123456"
}
Response
\{
"token": "token\_123456"
}

📘

Only provide one of user_id, user_intent_id, or business_profile_id

📘

Provide a user_intent_id if you are signing up the User for Astra’s services (Authorizing)

📘

Provide a user_id if you are signing them in (Authenticating)

📘

Provide a business_profile_id if you are signing up a business user (Authorizing)

📘

Please read Astra’s Guide to Trusted Authentication for additional information.

Step 05: Partner Identity Verification Token

Using the Session Token obtained from Step 04, call Astra’s POST Partner Identity Token endpoint to Authorize the User via API. The result of successfully calling this endpoint will result in the creation of an access_token and refresh_token. See the Appendix section below for recommendations on managing an access_token.

📘

There is an optional expires_in field that if not supplied in the request, defaults to 7200. The expires_in field denotes how many seconds from issue the access_token will expire. The upper and lower bounds for the expires_in parameter are 86400 and 300 respectively.

📘

UserConsentCapture must be set to true. Any other value will result in a failed
Authorization. By setting UserConsentCapture to true, you are confirming that the End-User has consented to Astra’s Terms and Privacy Policy.

Example:
POST /v1/partner/identity/token
Headers: {
"Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json",
"Authorization": "Basic ****",
}
{
"token": "token_123456", "user_consent_captured": true, "expires_in": 300
}
Response
{
"access_token": "access_token_abc123", "expires_in": 7200
"refresh_token": "refresh_token_abc123", "token_type": “Bearer”
}

Appendix

Recommendations on managing an access_token:

• Refresh the access_token when needed.
  • If you use an access_token, and it is expired, refresh it via
    https://docs.astra.finance/reference/post_v1-oauth-token
  • Optional: Keep track of the expiration date of an access_token and you can refresh it before you attempt to use it.
• If your refresh_token is expired, then generate a new access_token / refresh_token pair via the POST /v1/partner/identity/token resource.