> ## 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: Bearer Tokens and Request Headers

> Authenticate Synq API requests with a signed ID token. Covers token expiry, the Authorization header, and how to resolve 401 and 403 errors.

Every request to a protected Synq API endpoint must carry a valid Bearer token in the `Authorization` header. The token is a signed ID token obtained when you sign in to your Synq account — it already encodes your identity, tenant, and organization, so no additional scoping headers are required. Gather your token from the Synq dashboard, then include it on every call you make.

## Required Header

| Header          | Value            | Purpose                                                                                          |
| --------------- | ---------------- | ------------------------------------------------------------------------------------------------ |
| `Authorization` | `Bearer {token}` | Your signed ID token. Proves who you are and scopes the request to your tenant and organization. |

<Note>
  Your token encodes your **Tenant ID** and **Organization ID** as signed claims — you do not need to send them as separate headers. The API reads these values directly from your token on every request.
</Note>

## Obtaining Your Token

Sign in to your Synq account to receive an ID token. The dashboard surfaces this token under **Settings → Organization → API Credentials**. For programmatic use, authenticate via the Synq login flow and extract the ID token from the response.

## Token Expiry

ID tokens expire after **1 hour**. Refresh your token before it expires and use the new value in the `Authorization` header. A stale token returns a `401 Unauthorized` response.

<Warning>
  Never cache a token indefinitely. Build your client to detect a `401` response and automatically refresh the token before retrying the request.
</Warning>

## Full Request Example

The snippet below shows what a complete authenticated request looks like:

```http theme={null}
GET /api/v1/products HTTP/1.1
Host: api.synq.io
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
```

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.synq.io/api/v1/products" \
    -H "Authorization: Bearer $SYNQ_TOKEN" \
    -H "Content-Type: application/json"
  ```

  ```typescript TypeScript (fetch) theme={null}
  const response = await fetch("https://api.synq.io/api/v1/products", {
    method: "GET",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Synq API error ${response.status}: ${error.error}`);
  }

  const data = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  headers = {
      "Authorization": f"Bearer {token}",
      "Content-Type": "application/json",
  }

  response = requests.get(
      "https://api.synq.io/api/v1/products",
      headers=headers,
  )
  response.raise_for_status()
  data = response.json()
  ```
</CodeGroup>

## Error Responses

### 401 Unauthorized

You receive a `401` when the `Authorization` header is missing entirely, or the token is expired or malformed. The API rejects the request before any business logic runs.

```json theme={null}
{
  "error": "Unauthorized: Missing or invalid Authorization header"
}
```

**Fix:** Sign in to your Synq account to obtain a fresh ID token and retry the request with the new value in the `Authorization` header.

### 403 Forbidden

You receive a `403` when your token is valid but a required claim is missing from it, or your assigned role does not permit the action you are attempting.

```json theme={null}
{
  "error": "Forbidden: Missing tenantid claim"
}
```

```json theme={null}
{
  "error": "Forbidden: Insufficient permissions"
}
```

**Fix:** A missing claim (`tenantid`, `org_id`, or `role`) means your token was not issued with the expected scopes — contact your organization administrator to verify your account is fully provisioned. A permissions error means your role does not include the required access; ask your administrator to review your assigned role.

<Tip>
  Store your token as an environment variable in your development environment (for example, `SYNQ_TOKEN`). Reference it everywhere rather than hardcoding the value — this makes credential rotation safe and straightforward.
</Tip>