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

# Synq API Authentication: Tokens and Required Headers

> Learn how to obtain a Synq API token and attach the required Authorization, X-Tenant-ID, and X-Org-ID headers to every API request.

Every request to the Synq API must prove two things: who you are, and which tenant and organization you're acting on behalf of. Synq uses a short-lived Bearer token to handle identity — you sign in and receive a token, then pass that token as a Bearer credential on every request. Two additional headers tell the API exactly which tenant and organization scope to apply.

## How authentication works

When you sign in to Synq, the platform issues a signed **identity token** that encodes your identity and your assigned role. You attach this token to your API requests as a standard `Authorization: Bearer` header. The Synq API verifies the token on every request and rejects anything that is missing, expired, or malformed.

<Warning>
  Synq API tokens expire after **one hour**. Your application must refresh the token before it expires — or re-authenticate — to avoid `401 Unauthorized` errors on long-running sessions. Never cache a token and assume it is still valid.
</Warning>

## Required request headers

Include all three headers on every API request. Omitting any one of them results in a `401` or `403` error.

| Header          | Required | Description                                                                      |
| --------------- | -------- | -------------------------------------------------------------------------------- |
| `Authorization` | ✅ Yes    | Your Synq identity token, prefixed with `Bearer `. Example: `Bearer eyJhbGci...` |
| `X-Tenant-ID`   | ✅ Yes    | Your Synq Tenant ID, provided when your account is provisioned.                  |
| `X-Org-ID`      | ✅ Yes    | Your Synq Organization ID, scoped within your tenant.                            |

<Note>
  Your **Tenant ID** and **Org ID** are fixed values tied to your account — they do not change between requests. Retrieve them from your account settings in the [Synq Dashboard](https://app.synq.io).
</Note>

## Getting your API token

Sign in to the [Synq Dashboard](https://app.synq.io) with your Synq credentials. Navigate to your account settings and copy your **API token**. This token is your Bearer credential for all API calls.

Tokens expire after one hour. Return to your account settings to obtain a fresh token, or use the programmatic token refresh described below if you are building an application.

## Example authenticated requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.synq.io/api/v1/pim/products \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```javascript JavaScript (fetch) theme={null}
  const response = await fetch("https://api.synq.io/api/v1/pim/products", {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${token}`,
      "X-Tenant-ID": "YOUR_TENANT_ID",
      "X-Org-ID": "YOUR_ORG_ID",
      "Content-Type": "application/json",
    },
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Refreshing tokens in your application

If you are building an application that signs users in directly with their Synq credentials, request a fresh token before it expires and store it for subsequent API calls. Build refresh logic into your request retry flow so that a `401` response automatically triggers a new sign-in and retries the original request.

<Tip>
  Proactively refresh your token slightly before the one-hour mark rather than waiting for a `401` error. This prevents interruptions in latency-sensitive workflows.
</Tip>

## Common authentication errors

| HTTP Status        | Error                                     | What it means                                                                                                                                                                             |
| ------------------ | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid `Authorization` header | Your request did not include a Bearer token, or the token is expired, malformed, or has been revoked. Obtain a fresh token and retry.                                                     |
| `403 Forbidden`    | Missing or invalid tenant/org headers     | Your token is valid but does not carry the required tenant or org claims, or you lack the role required for this endpoint. Contact your account administrator to verify your permissions. |

<Note>
  A `403` on a valid token usually means your account has not been fully provisioned, or you are attempting to access a resource outside your organization's scope. Reach out to [Synq support](mailto:support@synq.io) if you believe your credentials are configured correctly.
</Note>