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

# API keys

> Learn how API keys work with the Passport API

API keys allow you to access your Passport account programmatically and integrate wallet passes into your applications.

Each API key inherits the permissions of the user who created it, giving access to all of that user's resources.

## Creating an API key

You can create an API key by following these steps:

<Steps>
  <Step title="Go to settings">
    Go to **Settings** > **API keys**.

    <img src="https://mintcdn.com/unblockedbrands/gtu0hwK9wYwAN1IU/images/auth/api-key-settings.png?fit=max&auto=format&n=gtu0hwK9wYwAN1IU&q=85&s=82121948ec0b5e2694d3de5e4e25d7fd" alt="Settings page with API tab highlighted" width="1920" height="1440" data-path="images/auth/api-key-settings.png" />
  </Step>

  <Step title="Create an API key">
    Click **"Create API key"** and give it a descriptive name.

    <img src="https://mintcdn.com/unblockedbrands/gtu0hwK9wYwAN1IU/images/auth/api-key-create.png?fit=max&auto=format&n=gtu0hwK9wYwAN1IU&q=85&s=ad50d5db950e7dd27e32b542d9747ee1" alt="Create API key form" width="1920" height="1440" data-path="images/auth/api-key-create.png" />
  </Step>

  <Step title="Store your API key">
    Once your API key is created, make sure to copy and store it in a safe place. You won't be able to see it again for security reasons. If it gets lost, you can create a new one.

    <img src="https://mintcdn.com/unblockedbrands/gtu0hwK9wYwAN1IU/images/auth/api-key-copy.png?fit=max&auto=format&n=gtu0hwK9wYwAN1IU&q=85&s=b39adf5685f89dff148a67d31a039f70" alt="Generated API key with copy button highlighted" width="1920" height="1440" data-path="images/auth/api-key-copy.png" />

    <Warning>
      Your API key grants full access to your Passport account. Keep it secure and never share it publicly.
    </Warning>
  </Step>

  <Step title="Use your API key">
    Now that you have your API key, you can use it to access your account's resources programmatically via any API request using the api-key header.

    ```bash theme={null}
    api-key: ub_live_xxxx
    ```
  </Step>
</Steps>

## Example Usage

Include your API key in the `api-key` header:

```bash theme={null}
curl -X GET 'https://api.ubpass.co/v1/wallet-pass' \
  -H 'api-key: YOUR_API_KEY_HERE'
```

### Example with a Real Request

```bash theme={null}
curl -X GET 'https://api.ubpass.co/v1/wallet-pass' \
  -H 'api-key: ub_live_abc123xyz456...' \
  -H 'Content-Type: application/json'
```

## Authentication Errors

If your API key is missing, invalid, or malformed, you'll receive authentication errors:

<AccordionGroup>
  <Accordion title="Missing API Key (401 Unauthorized)">
    When no API key is provided in the request headers, you'll receive a 401 Unauthorized response indicating that authentication is required.

    ```json theme={null}
    {
      "txId": "req-xxx",
      "timestamp": "2025-01-17T10:30:00Z",
      "errorCode": "UNAUTHORIZED", 
      "errorMessage": "Authentication required"
    }
    ```

    <Note>The exact error message may vary depending on the endpoint.</Note>
  </Accordion>

  <Accordion title="Invalid API Key (403 Forbidden)">
    When an invalid or malformed API key is provided, you'll receive a 403 Forbidden response indicating that access is denied.

    ```json theme={null}
    {
      "txId": "req-xxx",
      "timestamp": "2025-01-17T10:30:00Z",
      "errorCode": "FORBIDDEN",
      "errorMessage": "Access denied"
    }
    ```

    <Note>The exact error message may vary depending on the endpoint.</Note>
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Secure Storage" icon="lock">
    * Use environment variables in production
    * Never commit API keys to version control
    * Use different keys for development and production
    * Rotate keys regularly for security
  </Card>

  <Card title="Rate Limiting" icon="gauge">
    * API requests are rate limited to prevent abuse
    * Include proper error handling for `429` responses
    * Implement exponential backoff for retries
    * Cache responses when possible
  </Card>
</CardGroup>

### Environment Setup Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  // .env file
  PASSPORT_API_KEY=ub_live_your_api_key_here

  // app.js
  const API_KEY = process.env.PASSPORT_API_KEY;

  const response = await fetch('https://api.ubpass.co/v1/wallet-pass', {
    headers: {
      'api-key': API_KEY,
      'Content-Type': 'application/json'
    }
  });
  ```

  ```python Python theme={null}
  # .env file  
  PASSPORT_API_KEY=ub_live_your_api_key_here

  import os
  import requests

  API_KEY = os.getenv('PASSPORT_API_KEY')

  response = requests.get(
      'https://api.ubpass.co/v1/wallet-pass',
      headers={
          'api-key': API_KEY,
          'Content-Type': 'application/json'
      }
  )
  ```
</CodeGroup>

<Note>
  When you remove a user from your organization (or they leave your organization), all API keys associated with that user will stop working as well. Keep this in mind when managing users.
</Note>