403 Response When Creating a Bank Account

Overview

When linking a bank account by way of Astra's Create Account by Account and Routing endpoint, the payload requires an Institution ID. Providing an incorrect Institution ID can result in an 403 response. This article outlines how to remedy this response.

What is the Institution ID?

Every Astra client has its own Institution ID. It's a unique ID per client that allows our system to associate bank accounts created by account & routing number to the Astra client / program who registered them.

What if the Wrong Institution ID Is Used?

If the wrong or incorrect institution_id is specified in the payload, Astra will reject the request with a 403 response:

Common Mix-Ups:

• Using the Institution ID from another Sandbox client. If your team has several test clients (e.g. separate Sandbox and UAT clients).

• Using your Production Institution ID in Sandbox (or the other way around). Your Sandbox and Production Institution IDs may be different.

• Leaving a placeholder value from the docs or a Postman collection (e.g. astra_ins_id) in the request body.

Receiving a 403 Response

If the Institution ID provided in the payload doesn't match that of your client, the Create Account by Account and Routing endpoint returns the following 403 response:

{
  "code": 403,
  "name": "Forbidden",
  "description": "Client is not permitted to create account."
}

This means the institution_id in your request does not match the one specified for your client. Despite the wording, it is not a permission or setting that Astra needs to turn on for your client.

Finding and Using Your Institution ID

1. Log in to the Astra Dashboard for the environment you're calling (Sandbox or Production).

2. Go to the Client Details section and copy the Institution ID for the client you're using. It looks like astra_ins_ followed by a number.

3. Replace the institution_id in your request body with that value.

4. Resend the request to the secure endpoint for the same environment.

Example Request (Sandbox):

POST /v1/accounts/create
{
  "institution_id": "your_sandbox_institution_id",
  "name": "Operating Account",
  "bank_account_type": "checking",
  "account_number": "00123456789",
  "routing_number": "222222226"
}

If you've confirmed the Institution ID and still receive a 403, contact Astra Support with the environment, the request-id from the response headers, and the time of the request.