> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mycreditapp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorization

> Learn how to use authorization in the MyCreditApp API using the `Requester-Organization-ID` and `Target-Organization-ID` headers, `org_id` path parameter.

## Concepts

Authorization in MyCreditApp revolves around the **organization entity**.
**Each API client** you create belongs to a **specific organization**.
By default, every **API client** has **full access** to its own organization.

Another key concept is **connections**.
Connections allow one organization to interact with another.

To collaborate, one organization must **invite another organization** (or accept an invitation).
Once the invitation is accepted and the invited organization creates its own organization entity,
a **connection between the two organizations is established**.

<Info>Not all endpoints require authorization - only those that operate on organization-related data.</Info>

## Scenarios

There are **three authorization scenarios** when calling the API.
These scenarios describe **how organizations interact**.

* **Guest** – your organization accesses resources of another organization that invited you.
* **Host** – your organization accesses resources of a connected Guest organization.
* **Self** – your organization accesses its own resources.

<Info>
  Any organization api client with sufficient permissions can perform a **Self** call.
</Info>

These scenarios define how the `Requester-Organization-ID` and
`Target-Organization-ID` headers must be set.

## Path params

### `org_id`

The `org_id` path parameter identifies the specific organization whose data is being accessed or manipulated. Its value depends on the endpoint group and the ownership of the resource.

#### 1. General Organization Data

*Endpoint groups*:

* [Organizations](/api-reference/organizations);
* [Organization financial files](/api-reference/organization-financial-files).

In these groups, the resource owner is the organization identified by `org_id`.

* **Self:** `org_id` is your own ID.
* **Host accessing Guest:** `org_id` is the Guest's ID.
* **Guest accessing Host:** `org_id` is the Host's ID.
* **Requirement:** `org_id` must exactly match the `Target-Organization-ID` header.

#### 2. Host-Owned Resources

*Endpoint groups*:

* [Organization documents](/api-reference/organization-documents);
* [Organization document requests](/api-reference/organization-document-requests);
* [Organization analytics](/api-reference/organization-analytics);
* [Organization metrics](/api-reference/organization-metrics).

In these groups, the logic for `org_id` changes based on who is asking:

**Scenario A: Host requesting data about their Guest**
If you are a Host looking at your Guest's analytics or managing their documents:

* `Requester-Organization-ID`: **Host ID** (Your ID)
* `Target-Organization-ID`: **Host ID** (Your ID, because you own the analytics)
* `org_id` (path): **Guest ID**
* **Logic:** You are targeting your own "analytics engine" to get data about a specific guest from your list.

**Scenario B: Guest requesting their own data from a Host**
If you are a Guest looking at the analytics a Host has generated for you:

* `Requester-Organization-ID`: **Guest ID** (Your ID)
* `Target-Organization-ID`: **Host ID** (The organization that invited you)
* `org_id` (path): **Guest ID** (Must match your own ID)
* **Constraint:** A Guest can only specify their own ID in the path. You cannot access data about other guests of the same Host.

## Headers

### `Requester-Organization-ID`

The organization that **makes the request**.

* Always set to **your organization ID**;
* The scenario (Guest, Host, or Self) depends on the relationship with the target organization.

### `Target-Organization-ID`

The organization that the **request is directed at**:

* **Self** – same value as `Requester-Organization-ID`;
* **Host → Guest** – Guest organization ID;
* **Guest → Host** – Host organization ID.

<Warning>
  These headers are **mandatory** for all endpoints that require authorization.
  They ensure that requests are correctly routed according to organization relationships
  and established connections.
</Warning>

<Info>
  Not all endpoints require authorization - only those that operate on organization-related data.
</Info>

## Examples

1. **Host request**: get data of a connected Guest organization

   <ParamField path="org_id" type="uuid" required>
     Guest's organization ID
   </ParamField>

   <ParamField path="token" type="string" required>
     Your API client access token
   </ParamField>

   <ParamField path="requester-organization-id" type="uuid" required>
     Your organization ID
   </ParamField>

   <ParamField path="target-organization-id" type="uuid" required>
     Guest's organization ID
   </ParamField>

   <CodeGroup>
     ```curl cURL theme={null}
         curl --request GET \
           --url https://api.mycreditapp.ai/v1/organizations/{org_id} \
           --header 'Authorization: Bearer <token>' \
           --header 'Requester-Organization-ID: <requester-organization-id>' \
           --header 'Target-Organization-ID: <target-organization-id>'
     ```
   </CodeGroup>

2. **Self request**: upload a financial file of your organization
   <ParamField path="org_id" type="uuid" required>
     Your organization ID
   </ParamField>
   <ParamField path="token" type="string" required>
     Your API client access token
   </ParamField>
   <ParamField path="requester-organization-id" type="uuid" required>
     Your organization ID
   </ParamField>
   <ParamField path="target-organization-id" type="uuid" required>
     Your organization ID
   </ParamField>
   <ParamField path="currency" type="string" required>
     ISO 4217 currency
   </ParamField>
   <ParamField path="file" type="file" required>
     Financial File
   </ParamField>
   <CodeGroup>
     ```curl cURL theme={null}
         curl --request POST \
           --url https://api.mycreditapp.ai/v1/organizations/{org_id}/financial-files \
           --header 'Authorization: Bearer <token>' \
           --header 'Content-Type: multipart/form-data' \
           --header 'Requester-Organization-ID: <requester-organization-id>' \
           --header 'Target-Organization-ID: <target-organization-id>' \
           --form 'currency=<string>' \
           --form file='@example-file'
     ```
   </CodeGroup>

## Errors

During authorization, the following errors may occur:

* **organization\_being\_deleted** – The `Requester-Organization-ID` or `Target-Organization-ID` refers to an organization that is currently being deleted.
  <CodeGroup>
    ```json 409 theme={null}
        {
          "loc": [],
          "msg": "The organization is in the process of being deleted! The removal process may take up to 24 hours.",
          "type": "request",
          "code": "organization_being_deleted"
        }
    ```
  </CodeGroup>

* **unsupported\_crud\_operation** – This error occurs when the HTTP method used is not valid for the requested endpoint. It is not a common error but may appear in such cases.
  <CodeGroup>
    ```json 409 theme={null}
        {
          "loc": [],
          "msg": "Unsupported CRUD operation!",
          "type": "request",
          "code": "unsupported_crud_operation"
        }
    ```
  </CodeGroup>

* **access\_denied** – This indicates that the API client does not have permission to perform the requested action. Possible reasons include:
  * Invalid API client credentials.
  * No active connection exists between the organizations.
  * The API client does not have access to the requested resource or operation.
    <CodeGroup>
      ```json 409 theme={null}
      {
        "loc": [],
        "msg": "Access denied!",
        "type": "request",
        "code": "access_denied"
      }
      ```
    </CodeGroup>