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

# API Authentication

> How to authenticate with the Sticker Partner API

## Overview

The Sticker Partner API uses API key authentication. Your API key identifies your partner account and authorizes access to your organizations and users.

## Getting API Credentials

Contact the Sticker team to receive:

* **Partner ID** (UUID) - Your unique partner identifier
* **API Key** (string) - Starts with `sk_live_` or `sk_test_`

```bash theme={null}
# Store these as environment variables
STICKER_PARTNER_ID=550e8400-e29b-41d4-a716-446655440000
STICKER_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

<Warning>
  **Keep your API key secret!** Never expose it in frontend code, public repositories, or browser network requests.
</Warning>

## Authentication Headers

Different endpoints use different authentication headers:

### Organization Setup Endpoint

```bash theme={null}
POST /v1/organizations/setup
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
```

### Partner Handshake Endpoint

```bash theme={null}
POST /v1/partner/handshake
X-API-Key: sk_live_your_api_key
Content-Type: application/json
```

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  // Organization Setup - uses Authorization: Bearer
  const setupResponse = await fetch('https://api.usesticker.com/v1/organizations/setup', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.STICKER_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ /* ... */ })
  });

  // Partner Handshake - uses X-API-Key
  const handshakeResponse = await fetch('https://api.usesticker.com/v1/partner/handshake', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.STICKER_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ /* ... */ })
  });
  ```

  ```python Python theme={null}
  import httpx
  import os

  api_key = os.getenv("STICKER_API_KEY")

  # Organization Setup - uses Authorization: Bearer
  setup_response = await client.post(
      "https://api.usesticker.com/v1/organizations/setup",
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json",
      },
      json={...}
  )

  # Partner Handshake - uses X-API-Key
  handshake_response = await client.post(
      "https://api.usesticker.com/v1/partner/handshake",
      headers={
          "X-API-Key": api_key,
          "Content-Type": "application/json",
      },
      json={...}
  )
  ```
</CodeGroup>

## Error Responses

### 401 Unauthorized

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "code": "UNAUTHORIZED"
}
```

**Common causes:**

* Missing authentication header
* Invalid API key
* Using wrong header (`Authorization` vs `X-API-Key`)
* Using production key in sandbox or vice versa

### 403 Forbidden

```json theme={null}
{
  "error": "Forbidden",
  "message": "API key does not have required scope",
  "code": "FORBIDDEN"
}
```

**Common causes:**

* API key lacks required permissions
* Trying to access resources from another partner

## Security Best Practices

<AccordionGroup>
  <Accordion title="Server-Side Only" icon="server">
    **Never expose your API key in client-side code.**

    ```javascript theme={null}
    // ❌ BAD - API key in frontend
    fetch('https://api.usesticker.com/v1/partner/handshake', {
      headers: { 'X-API-Key': 'sk_live_xxx' }  // Exposed!
    });

    // ✅ GOOD - Call through your backend
    fetch('/api/supplies/auth', {
      method: 'POST',
      body: JSON.stringify({ userId })
    });
    ```
  </Accordion>

  <Accordion title="Environment Variables" icon="key">
    Store API keys in environment variables:

    ```bash theme={null}
    # .env (never commit!)
    STICKER_API_KEY=sk_live_xxxxx
    ```

    ```javascript theme={null}
    // Read from environment
    const apiKey = process.env.STICKER_API_KEY;
    ```
  </Accordion>

  <Accordion title="Key Rotation" icon="rotate">
    If your key is compromised:

    1. Contact Sticker support immediately
    2. We'll issue a new key
    3. Update your environment variables
    4. Redeploy your application
  </Accordion>
</AccordionGroup>

## Session Tokens vs API Keys

|                   | API Keys                   | Session Tokens                 |
| ----------------- | -------------------------- | ------------------------------ |
| **Used for**      | Server-to-server API calls | User authentication in iframe  |
| **Lifetime**      | Permanent until rotated    | 5 minutes                      |
| **Usage**         | Unlimited                  | Single-use                     |
| **Obtained from** | Sticker team               | Handshake endpoint             |
| **Stored**        | Environment variables      | Never stored (use immediately) |

## Testing Authentication

```bash theme={null}
# Test Organization Setup endpoint
curl -X POST https://api.usesticker.com/v1/organizations/setup \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"internalOrgId":"test","organizationName":"Test","internalUserId":"user","user":{"firstName":"Test","lastName":"User","email":"test@example.com"}}'

# Test Handshake endpoint
curl -X POST https://api.usesticker.com/v1/partner/handshake \
  -H "X-API-Key: sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"internal_user_id":"user"}'
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Organization Setup" icon="building" href="/api-reference/organization-setup">
    Provision organizations and users
  </Card>

  <Card title="Partner Handshake" icon="handshake" href="/api-reference/handshake">
    Authenticate users for iframe access
  </Card>
</CardGroup>