> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/documentation/getting-started/authentication.md).

# Authentication

Learn how to authenticate your requests to the Pullbay API using Bearer tokens. This guide covers getting your API key, understanding test vs. live keys, and implementing authentication in multiple programming languages.

## Getting Your API Key

Every Pullbay API request requires authentication with an API key. Here's how to find and copy your key:

{% stepper %}
{% step %}

#### Sign in to your [Pullbay Dashboard](https://dashboard.pullbay.com/)

{% endstep %}

{% step %}

#### Click **API Keys** in the left sidebar

{% endstep %}

{% step %}

#### You'll see two keys listed:

* **Test Key** (prefixed with `test_`) — Use this for development and testing
* **Live Key** (prefixed with `live_`) — Use this for production applications
  {% endstep %}

{% step %}

#### Click the copy icon next to the key you want to use

{% endstep %}

{% step %}

#### Paste your key into your application or configuration file

{% endstep %}
{% endstepper %}

**Never share your API keys.** Treat them like passwords and keep them secure at all times.

## Test vs. Live Keys

Pullbay provides separate test and live API keys. Understanding the difference helps you avoid mistakes and manage your API usage effectively.

| Aspect              | Test Key (`test_*`)                                   | Live Key (`live_*`)                              |
| ------------------- | ----------------------------------------------------- | ------------------------------------------------ |
| **Purpose**         | Development, testing, and experimentation             | Production applications and live data            |
| **Data**            | Sample data and test reviews                          | Real app store data                              |
| **Credit Usage**    | Counts against your monthly credits                   | Counts against your monthly credits              |
| **Rate Limits**     | Same as live keys                                     | Same as test keys                                |
| **Revocation**      | Can revoke without affecting production               | Revoke carefully—it will break live applications |
| **Recommended Use** | Sandbox environment, CI/CD pipelines, feature testing | Customer-facing apps, production services        |

### Why Separate Keys?

Having separate test and live keys provides several important benefits:

* **Environment Separation** — Keep development isolated from production
* **Usage Tracking** — Monitor your API calls by environment (test vs. production)
* **Accident Prevention** — Reduce the risk of accidentally using real data in development
* **Independent Revocation** — Revoke a compromised key without taking down all your applications
* **Team Permissions** — Give developers test keys and restrict live key access to authorized team members

### Using Both Keys

You can (and should) use both keys in your applications:

```python
# In your development environment
if os.getenv('ENV') == 'production':
    api_key = os.getenv('PULLBAY_LIVE_KEY')
else:
    api_key = os.getenv('PULLBAY_TEST_KEY')
```

Both key types access the same endpoints and consume the same API credits. The only difference is the prefix and which environment you use them in.

## How to Authenticate

Every request to the Pullbay API must include your API key in the `Authorization` header using the Bearer token scheme:

```
Authorization: Bearer YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual test or live key (including the `test_` or `live_` prefix).

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET "https://api.pullbay.com/v1/app-store/reviews?app_id=284882215" \
  -H "Authorization: Bearer test_abc123xyz789"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

api_key = "test_abc123xyz789"
url = "https://api.pullbay.com/v1/app-store/reviews"
headers = {
    "Authorization": f"Bearer {api_key}"
}

response = requests.get(url, headers=headers, params={"app_id": "284882215"})
data = response.json()
print(data)
```

{% endtab %}

{% tab title="Node.js (Axios)" %}

```javascript
const axios = require('axios');

const apiKey = 'test_abc123xyz789';
const url = 'https://api.pullbay.com/v1/app-store/reviews';

const response = await axios.get(url, {
  params: { app_id: '284882215' },
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

console.log(response.data);
```

{% endtab %}

{% tab title="Node.js (Fetch)" %}

```javascript
const apiKey = 'test_abc123xyz789';
const url = 'https://api.pullbay.com/v1/app-store/reviews?app_id=284882215';

const response = await fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$apiKey = 'test_abc123xyz789';
$url = 'https://api.pullbay.com/v1/app-store/reviews?app_id=284882215';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
?>
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	apiKey := "test_abc123xyz789"
	url := "https://api.pullbay.com/v1/app-store/reviews?app_id=284882215"

	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", apiKey))

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	body, _ := ioutil.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

{% endtab %}
{% endtabs %}

## Authentication Errors

If your authentication fails, you'll receive a 401 Unauthorized response. Here are common causes and solutions:

| Error                | Cause                         | Solution                                                                                         |
| -------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------ |
| **401 Unauthorized** | Missing or invalid API key    | Verify your key is correct and included in the `Authorization` header                            |
| **401 Unauthorized** | Key revoked or expired        | Generate a new key in your dashboard and update your application                                 |
| **401 Unauthorized** | Incorrect header format       | Check the header format: `Authorization: Bearer YOUR_API_KEY` (include the space after "Bearer") |
| **401 Unauthorized** | Key used in wrong environment | Ensure you're using test keys in development and live keys in production                         |

### Example 401 Response

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "type": "authentication_error"
  }
}
```

## API Key Management

### Creating a New Key

{% stepper %}
{% step %}

#### Go to your [Pullbay Dashboard](https://dashboard.pullbay.com/)

{% endstep %}

{% step %}

#### Click **API Keys** in the sidebar

{% endstep %}

{% step %}

#### Click **Create New Key**

{% endstep %}

{% step %}

#### Choose **Test** or **Live**

{% endstep %}

{% step %}

#### Optionally add a description (e.g., "Mobile App", "Analytics Dashboard")

{% endstep %}

{% step %}

#### Click **Create**

{% endstep %}

{% step %}

#### Copy the new key immediately—you won't be able to see it again

{% endstep %}
{% endstepper %}

### Rotating Your API Key

Key rotation is important for security. If you suspect a key is compromised or just want to rotate regularly, follow these steps:

{% stepper %}
{% step %}

#### Create a New Key

* Go to **API Keys** and create a new key with the same environment (test or live)
  {% endstep %}

{% step %}

#### Update Your Applications

* Update all your applications and services to use the new key
* Test thoroughly in a staging environment first
* Deploy the changes to all instances
  {% endstep %}

{% step %}

#### Verify the New Key Works

* Make test API calls with the new key
* Monitor your dashboard for successful requests
* Check for any errors or failed requests
  {% endstep %}

{% step %}

#### Revoke the Old Key

* Once you're confident the new key is working everywhere, click the **Revoke** button next to the old key
* This immediately invalidates the old key
  {% endstep %}
  {% endstepper %}

### Revoking a Key

If your key is compromised or you no longer need it:

{% stepper %}
{% step %}

#### Go to **API Keys** in your dashboard

{% endstep %}

{% step %}

#### Find the key you want to revoke

{% endstep %}

{% step %}

#### Click the **Revoke** button

{% endstep %}

{% step %}

#### Confirm the action

{% endstep %}
{% endstepper %}

**Warning:** Revoking a key immediately invalidates it. Any applications using that key will start receiving 401 errors. Make sure you've updated all your code before revoking.

### Viewing Key Usage

To see how many API calls have been made with each key:

{% stepper %}
{% step %}

#### Go to **API Keys** and find your key

{% endstep %}

{% step %}

#### Click **View Usage** or **View Details**

{% endstep %}

{% step %}

#### See a breakdown of:

* Total requests made with this key
* Requests by endpoint
* Requests by date
* Credits consumed
  {% endstep %}
  {% endstepper %}

## Key Security Best Practices

Protecting your API keys is critical. Follow these security guidelines:

### Storage & Configuration

* **Use environment variables** — Store keys in `.env` files or environment variables, not hardcoded in source code
* **Keep keys out of version control** — Add `.env` files and credential files to your `.gitignore`
* **Use a secrets manager** — For larger deployments, use AWS Secrets Manager, HashiCorp Vault, or similar tools
* **Separate keys per environment** — Use test keys in dev/staging and live keys only in production

### Access & Distribution

* **Limit key access** — Only give live keys to authorized team members and production systems
* **Use key descriptions** — Label keys by application or purpose so you know where each key is used
* **Rotate periodically** — Change your keys every 90 days or whenever team membership changes
* **Audit key usage** — Regularly check your dashboard to see which keys are being used

### What NOT to Do

* **Don't commit keys to Git** — Keys in version control history are exposed even if you later remove them
* **Don't include keys in client-side code** — JavaScript in a web browser is readable to anyone
* **Don't share keys via email or chat** — Use secure password managers or key management systems instead
* **Don't use the same key everywhere** — Use different keys for mobile apps, backend services, and third-party integrations
* **Don't leave keys in logs** — Make sure log files don't accidentally capture API keys

## Common Questions

<details>

<summary>Can I have multiple API keys?</summary>

**Yes.** You can create as many keys as needed. Common patterns include:

* One test key for development, another for staging
* Separate keys for different applications
* Keys for different team members
* Keys with different permissions (if supported)

Each key independently accesses the same endpoints and data.

</details>

<details>

<summary>What's the difference between test and live keys?</summary>

**The prefix and intended use.** Test keys are prefixed with `test_` and live keys with `live_`. Both access the same API endpoints and consume the same credits. The difference is:

* Test keys are for development and testing
* Live keys are for production applications
* Separating them helps you avoid mistakes and track usage by environment

</details>

<details>

<summary>How do I rotate my API key without downtime?</summary>

Follow the key rotation steps above:

1. Create a new key alongside your old one
2. Update all your applications to use the new key (test thoroughly)
3. Deploy the updates to all instances
4. Verify everything is working
5. Revoke the old key

This approach ensures you have a working key throughout the transition.

</details>

<details>

<summary>What should I do if my API key is compromised?</summary>

**Act immediately:**

1. Go to your dashboard
2. Click **Revoke** on the compromised key
3. Create a new key
4. Update all your applications with the new key
5. Deploy the changes
6. Monitor your usage dashboard for any unauthorized requests that occurred while the key was exposed

If you used a live key, also review your recent API calls and usage to check for suspicious activity.

</details>

<details>

<summary>Can I see which endpoints a key has access to?</summary>

**Yes.** Go to **API Keys**, select a key, and view its details. Depending on your plan, you may see:

* All endpoints (typically for test and live keys)
* Restricted endpoints (if you've set up fine-grained permissions)
* Usage statistics by endpoint

</details>

<details>

<summary>How are API credits charged for authenticated requests?</summary>

**1 credit per successful request.** When you make an authenticated API call:

* If it succeeds (status 200), it uses 1 credit
* If it fails with a client error (4xx), it uses 1 credit
* If it fails with a server error (5xx), it may not consume credits (depending on the error)
* Rate-limited requests (429) don't consume credits

Check the `meta.credits_used` field in the response for the exact credit cost of a request.

</details>

Start building with authenticated API requests today!


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pullbay.com/documentation/getting-started/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.