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

# Generating API Keys

> Create API credentials to authenticate your requests.

Every request to the Orchestra API requires authentication via an API key. This page explains how to create, manage, and secure your API keys.

## Create an API Key

<Steps>
  <Step title="Open API Key Settings">
    In the Orchestra portal, go to **[API Keys](https://portal.orchestrasolutions.com/#/apikey/create)**.
  </Step>

  <Step title="Create New Key">
    Click **Create** to generate a new key.
  </Step>

  <Step title="Configure the Key">
    | Field                    | Description                                                             |
    | ------------------------ | ----------------------------------------------------------------------- |
    | **Name**                 | A descriptive label (e.g., "Production Server", "Development", "CI/CD") |
    | **Assign it to my user** | Check this to assign the key to your own user account                   |
    | **Username**             | Or select a different user from the dropdown to assign the key to them  |

    <Note>
      You can ignore the user settings entirely. If no user is selected, the API key is automatically assigned to your current user.
    </Note>
  </Step>

  <Step title="Save and Copy">
    Click **Save**. Your new API key will be displayed in a popup dialog.

    <Warning>
      **Copy the key immediately and save it securely.** Once you close the popup, you cannot view the API key again. If you lose it, you'll need to create a new one.
    </Warning>
  </Step>
</Steps>

## Using Your API Key

Include the API key in the `X-Api-Key` header of every request:

```bash theme={null}
curl -X POST https://api.orchestrasolutions.com/PaymentGateway/charge \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_api_key_here" \
  -d '{ ... }'
```

## User Assignment

When you assign an API key to a specific user:

* The key can only access Payment Gateway Accounts assigned to that user
* Transactions are logged under that user's activity
* Useful for multi-tenant setups or restricting access

If you don't assign a user, the key has access to all Payment Gateway Accounts in your organization.

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Never expose keys in client code" icon="eye-slash">
    API keys should only exist on your server. Never include them in frontend JavaScript, mobile apps, or public repositories.
  </Card>

  <Card title="Use environment variables" icon="terminal">
    Store keys in environment variables, not in code. Use secrets managers in production.
  </Card>

  <Card title="Rotate keys periodically" icon="rotate">
    Create new keys and deprecate old ones on a regular schedule, especially if you suspect exposure.
  </Card>

  <Card title="Use separate keys per environment" icon="layer-group">
    Create distinct keys for development, staging, and production. Revoke dev keys if compromised without affecting production.
  </Card>
</CardGroup>

## Rotating Keys

To rotate an API key:

1. Create a new key
2. Update your application to use the new key
3. Verify the new key works in production
4. Delete the old key

<Note>
  There's no downtime during rotation. Both keys work until you delete the old one.
</Note>

## Revoking Keys

To revoke a compromised or unused key:

1. Go to **[API Keys](https://portal.orchestrasolutions.com/#/apikey/create)** in the portal
2. Find the key by name
3. Click **Delete** or **Revoke**

The key stops working immediately.

## Choose Your Integration Path

You're ready to accept payments. Choose how you want to integrate:

<CardGroup cols={2}>
  <Card title="Payments Library" icon="browser" href="/quickstart">
    **Recommended for most integrations**

    Pre-built payment UI with Google Pay, Apple Pay, and card entry. Handles 3D Secure automatically. Keeps you out of PCI scope.
  </Card>

  <Card title="REST API" icon="code" href="/quickstart">
    **For custom payment flows**

    Direct HTTP calls from your backend. Full control over UI. Use when you have existing payment infrastructure or need maximum flexibility.
  </Card>
</CardGroup>

<Note>
  Not sure which to choose? See the [detailed comparison](/concepts/api-vs-library).
</Note>