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

# Authentication

> All requests to the HIFI API must be authenticated using API keys. This guide covers how to create, secure, and manage your keys.

## Prerequisites

To get your API keys, you'll need access to the HIFI Dashboard. **Don't have access?** Schedule a call with our team.

<Card title="Request access" href="https://app.hifi.com/request-access">
  Describe your use case and schedule an intro call
</Card>

## API Environments

HIFI provides two environments for development and production:

| Environment    | Base URL                            | Purpose                                             |
| :------------- | :---------------------------------- | :-------------------------------------------------- |
| **Sandbox**    | `https://sandbox.hifibridge.com`    | Testing and development with simulated transactions |
| **Production** | `https://production.hifibridge.com` | Live transactions with real money movement          |

## Creating API Keys

### Access the API Keys Section

1. Log in to the [HIFI Dashboard](https://app.hifi.com)
2. Navigate to **Developer** → **API Keys**

### Select Your Environment

Choose which environment you're creating keys for:

* **Sandbox** - For testing and development
* **Production** - For live operations

<Info>
  **Best Practice:** Start with sandbox keys to build and test your integration before moving to production.
</Info>

### Generate a New API Key

1. Click the **"Create API Key"** or **"New API Key"** button
2. Provide a descriptive name that identifies the key's purpose\
   Examples:
   * "Production Web App"
   * "Staging Server"
   * "Mobile App Development"
   * "Webhook Service"
3. Click **"Generate"** to create the key

### Copy and Secure Your API Key

<Warning>
  API keys are shown only once at creation. If you lose your key, you'll need to generate a new one and update your application.
</Warning>

**After generation:**

1. ✅ **Immediately copy the API key** from the dashboard
2. ✅ **Store it securely** in your environment variables or secrets manager
3. ✅ **Never commit keys** to version control (Git, SVN, etc.)
4. ✅ **Never expose keys** in client-side code or public repositories

**Example of secure storage:**

```bash theme={null}
# .env file (add to .gitignore)
HIFI_API_KEY=zpka_1234567890abcdef
HIFI_ENVIRONMENT=sandbox
```

## Managing API Keys

### Deleting API Keys

If a key is compromised or no longer needed:

1. Navigate to **Developer** → **API Keys** in the dashboard
2. Find the key you want to delete
3. Click **"Delete"** or the delete icon
4. Confirm the deletion

<Warning>
  Deleted keys stop working immediately. Ensure you've updated your application with a new key before deleting the old one.
</Warning>

## API Key Security Requirements

All customers and integrators are required to handle HIFI API keys in accordance with the following security practices.

### Transmission

* **Only transmit API keys over encrypted channels (HTTPS/TLS).** Never send a key via email, chat, SMS, or any unencrypted medium.
* When making API requests, always use the `Authorization: Bearer YOUR_API_KEY` header over HTTPS — never include keys in URLs or unencrypted request bodies.

### Storage

* Store API keys in environment variables or a dedicated secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager).
* **Never hardcode keys** in application source code or configuration files committed to version control.
* **Never expose keys** in client-side code, browser bundles, or public repositories.
* Restrict access to keys using least-privilege principles — only the systems and personnel that require the key should have access to it.

### Rotation

* Rotate API keys **at least once every 12 months** as part of routine key hygiene.
* Rotate immediately if a key is suspected to be compromised, accidentally exposed, or if a team member with access departs.
* **Rotation procedure:**
  1. Generate a new API key in the HIFI Dashboard under **Developer** → **API Keys**
  2. Update your application or secrets manager with the new key
  3. Verify the new key is working correctly
  4. Delete the old key from the dashboard

<Info>
  If you believe your key has been compromised, delete it immediately and generate a replacement. Contact [support@hifi.com](mailto:support@hifi.com) if you need assistance.
</Info>

## Testing Your API Key

Verify your API key is working correctly with the ping endpoint:

```bash theme={null}
curl -X GET "https://sandbox.hifibridge.com/ping" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Successful response:**

```json theme={null}
{
  "message": "pong"
}
```

**Authentication error:**

```json theme={null}
{
  "error": "Not authorized"
}
```

***

## Next Steps

Now that you have your API keys set up:

* [**Quickstart Guide**](/docs/quickstart) - Build your first integration
* [**API Reference**](https://docs.hifi.com/api-reference) - Explore available endpoints
* [**Webhooks**](/docs/webhooks) - Set up real-time event notifications
* [**Error Handling**](https://docs.hifi.com/docs/api/errors) - Learn how to handle API errors gracefully

***

## Getting Help

**Having trouble with authentication?**

1. ✅ Verify your API key is active in the dashboard
2. ✅ Check the header format: `Authorization: Bearer YOUR_KEY`
3. ✅ Ensure you're using the correct environment endpoint

**Still need help?**

* 📧 **Email:** [support@hifi.com](mailto:support@hifi.com)
* 💬 **Slack:** Message us in our shared Slack channel