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

# Authentication

> Get partner and business tokens for API access

Thred uses a two-tier OAuth2 system for secure multi-tenant access.

<CardGroup cols={2}>
  <Card title="Partner-Scoped Token" icon="building">
    **Backend only**

    Manage multiple businesses:

    * List all businesses
    * Create new businesses
    * Get business-scoped tokens
  </Card>

  <Card title="Business-Scoped Token" icon="user">
    **Frontend safe**

    Access single business:

    * Invoices and payments
    * Reports and GL
    * Isolated to one business
  </Card>
</CardGroup>

<Warning>
  **Security: Never use partner-scoped tokens on the frontend**

  Partner-scoped tokens grant access to ALL businesses under your partnership. Exposing them in frontend code allows users to access other businesses' financial data.

  Always use business-scoped tokens in the frontend - they're scoped to a single business and safe for end users.
</Warning>

***

## Get Partner-Scoped Token

Exchange your credentials for a partner-scoped token:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://sandbox.thredfi.com/v1/platform/oauth2/token/ \
    -H "Authorization: Basic $(echo -n 'PARTNER_UUID:API_KEY' | base64)" \
    -d "grant_type=client_credentials"
  ```

  ```python Python theme={null}
  import requests
  import base64

  partner_uuid = "your-partner-uuid"
  api_key = "your-api-key"

  credentials = f"{partner_uuid}:{api_key}"
  encoded = base64.b64encode(credentials.encode()).decode()

  response = requests.post(
      "https://sandbox.thredfi.com/v1/platform/oauth2/token/",
      headers={"Authorization": f"Basic {encoded}"},
      data={"grant_type": "client_credentials"}
  )

  partner_token = response.json()["access_token"]
  ```

  ```javascript JavaScript theme={null}
  const partnerUuid = 'your-partner-uuid';
  const apiKey = 'your-api-key';
  const credentials = btoa(`${partnerUuid}:${apiKey}`);

  const response = await fetch(
    'https://sandbox.thredfi.com/v1/platform/oauth2/token/',
    {
      method: 'POST',
      headers: { 'Authorization': `Basic ${credentials}` },
      body: new URLSearchParams({ grant_type: 'client_credentials' })
    }
  );

  const { access_token } = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

***

## Get Business-Scoped Token

Exchange partner-scoped token for business-scoped token:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://sandbox.thredfi.com/v1/platform/BUSINESS_ID/oauth2/token/ \
    -H "Authorization: Bearer PARTNER_TOKEN"
  ```

  ```python Python theme={null}
  response = requests.post(
      f"https://sandbox.thredfi.com/v1/platform/{business_id}/oauth2/token/",
      headers={"Authorization": f"Bearer {partner_token}"}
  )

  business_token = response.json()["access_token"]
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://sandbox.thredfi.com/v1/platform/${businessId}/oauth2/token/`,
    {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${partnerToken}` }
    }
  );

  const { access_token: businessToken } = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "business_access"
}
```

***

## Token Usage

<Tabs>
  <Tab title="Partner-Scoped Token">
    Use for managing businesses:

    * [`GET /v1/platform/businesses/`](/api-reference/business-management/list-businesses) - List all businesses
    * [`POST /v1/platform/businesses/`](/api-reference/business-management/create-business) - Create business
    * [`POST /v1/platform/{business_id}/oauth2/token/`](/api-reference/authentication/get-business-token) - Get business-scoped token

    **Location:** Backend server only
  </Tab>

  <Tab title="Business-Scoped Token">
    Use for business operations:

    * All business-specific endpoints
    * Invoices, bills, customers, vendors
    * Payments, refunds
    * Reports, GL access
    * Frontend SDK authentication

    **Location:** Backend server + frontend SDK
  </Tab>
</Tabs>

***

## Token Lifecycle

<Steps>
  <Step title="Tokens expire after 1 hour">
    Both token types expire after 3600 seconds.
  </Step>

  <Step title="Handle expiration">
    When you receive `401 Unauthorized`:

    * Re-authenticate to get fresh token
    * Retry the failed request
  </Step>

  <Step title="Best practice">
    Cache tokens and refresh before expiry to avoid disruptions.
  </Step>
</Steps>

***

## Security Best Practices

<AccordionGroup>
  <Accordion title="Never expose credentials">
    Store partner UUID and API key securely:

    * Environment variables
    * Secrets manager (AWS Secrets Manager, HashiCorp Vault)
    * Never commit to source control
  </Accordion>

  <Accordion title="Use HTTPS only">
    All API calls must use HTTPS. HTTP requests will be rejected.
  </Accordion>

  <Accordion title="Rotate API keys periodically">
    Regenerate keys every 90 days via Partner Portal for security hygiene.
  </Accordion>
</AccordionGroup>

***

Tokens secured. Now [embed the accounting UI](/implementation/frontend-sdk) in your platform.