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

# Testing Your Integration

> How to test your Signa integration safely.

Signa does not currently provide a dedicated sandbox environment. For integration testing, we recommend creating a **separate test organization** in the [dashboard](https://app.signa.so) with its own API key. You can then scope that key's usage, limits, and billing independently from your production organization.

## Recommended Workflow

1. **Create a test organization** from the dashboard.
2. **Issue a dedicated API key** for that organization and store it in your CI provider's secrets manager (e.g. `SIGNA_TEST_API_KEY`).
3. **Point integration tests at `https://api.signa.so`** using the test key. All keys use the format `sig_{48 hex chars}` — there is no separate base URL.
4. **Keep production keys out of CI**. Treat every API key as a credential regardless of which organization it belongs to.

## Integration Test Examples

### Basic: Verify Authentication

<CodeGroup>
  ```typescript TypeScript (Vitest) theme={null}
  import { describe, it, expect } from 'vitest';

  const API_KEY = process.env.SIGNA_TEST_API_KEY!;
  const BASE_URL = 'https://api.signa.so/v1';

  describe('Signa API Authentication', () => {
    it('should authenticate with a valid key', async () => {
      const response = await fetch(`${BASE_URL}/offices`, {
        headers: { Authorization: `Bearer ${API_KEY}` },
      });

      expect(response.status).toBe(200);
      const body = await response.json();
      expect(body.object).toBe('list');
    });

    it('should reject an invalid key', async () => {
      const response = await fetch(`${BASE_URL}/offices`, {
        headers: { Authorization: 'Bearer sig_invalid_key' },
      });

      expect(response.status).toBe(401);
    });
  });
  ```

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

  API_KEY = os.environ["SIGNA_TEST_API_KEY"]
  BASE_URL = "https://api.signa.so/v1"

  def test_valid_authentication():
      response = requests.get(
          f"{BASE_URL}/offices",
          headers={"Authorization": f"Bearer {API_KEY}"},
      )
      assert response.status_code == 200
      assert response.json()["object"] == "list"

  def test_invalid_authentication():
      response = requests.get(
          f"{BASE_URL}/offices",
          headers={"Authorization": "Bearer sig_invalid_key"},
      )
      assert response.status_code == 401
  ```
</CodeGroup>

### Search and Paginate

<CodeGroup>
  ```typescript TypeScript (Vitest) theme={null}
  import { Signa } from '@signa-so/sdk';
  import { describe, it, expect } from 'vitest';

  const signa = new Signa({ api_key: process.env.SIGNA_TEST_API_KEY! });

  describe('Search and pagination', () => {
    it('should search and paginate through results', async () => {
      // First page
      const page1 = await signa.trademarks.list({
        query: 'health',
        limit: 10,
      });

      expect(page1.data.length).toBe(10);
      expect(page1.has_more).toBe(true);
      expect(page1.pagination.cursor).toBeTruthy();

      // Second page
      const page2 = await signa.trademarks.list({
        query: 'health',
        limit: 10,
        cursor: page1.pagination.cursor,
      });

      expect(page2.data.length).toBeGreaterThan(0);

      // Verify no duplicates across pages
      const page1Ids = new Set(page1.data.map((t) => t.id));
      const page2Ids = page2.data.map((t) => t.id);
      for (const id of page2Ids) {
        expect(page1Ids.has(id)).toBe(false);
      }
    });
  });
  ```

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

  API_KEY = os.environ["SIGNA_TEST_API_KEY"]
  BASE_URL = "https://api.signa.so/v1"

  def test_search_and_paginate():
      headers = {"Authorization": f"Bearer {API_KEY}"}

      # First page
      page1 = requests.post(
          f"{BASE_URL}/trademarks",
          headers=headers,
          json={"query": "health", "limit": 10},
      ).json()

      assert len(page1["data"]) == 10
      assert page1["has_more"] is True

      # Second page
      page2 = requests.post(
          f"{BASE_URL}/trademarks",
          headers=headers,
          json={
              "query": "health",
              "limit": 10,
              "cursor": page1["pagination"]["cursor"],
          },
      ).json()

      assert len(page2["data"]) > 0

      # Verify no duplicates
      page1_ids = {t["id"] for t in page1["data"]}
      page2_ids = {t["id"] for t in page2["data"]}
      assert page1_ids.isdisjoint(page2_ids)
  ```
</CodeGroup>

### Batch Fetch with Error Handling

```typescript theme={null}
import { Signa } from '@signa-so/sdk';
import { describe, it, expect } from 'vitest';

const signa = new Signa({ api_key: process.env.SIGNA_TEST_API_KEY! });

describe('Batch operations', () => {
  it('should handle mixed success and not-found in batch', async () => {
    const response = await signa.trademarks.batch({
      ids: ['tm_abc123', 'tm_nonexistent_id', 'tm_def456'],
    });

    // Overall request succeeds
    expect(response.data).toHaveLength(3);

    // First and third items succeed
    expect(response.data[0].status).toBe('success');

    // Second item is not found
    expect(response.data[1].status).toBe('error');
    expect(response.data[1].error.type).toBe('not_found');

    // Third item succeeds
    expect(response.data[2].status).toBe('success');
  });
});
```

***

## CI/CD Integration

### Environment Variables

Set these in your CI pipeline:

| Variable             | Value     | Description                        |
| -------------------- | --------- | ---------------------------------- |
| `SIGNA_TEST_API_KEY` | `sig_...` | API key for your test organization |

### GitHub Actions Example

```yaml theme={null}
name: Integration Tests
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npm run test:integration
        env:
          SIGNA_TEST_API_KEY: ${{ secrets.SIGNA_TEST_API_KEY }}
```

<Warning>
  Store API keys in your CI provider's secrets manager. Treat every key as a credential.
</Warning>