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

# Authentication

> API reference for authenticating with the Merchant API using API keys

## Overview

The Merchant API uses API key authentication via the `Authorization` header. All requests must include a valid API key with the appropriate permissions.

## Authentication Method

### Header Format

```http theme={null}
Authorization: Bearer uwk_YOUR_API_KEY_HERE
```

<ParamField header="Authorization" type="string" required>
  Bearer token containing your API key. Must start with the prefix `uwk_`
</ParamField>

## API Key Format

Universal Wallet API keys follow this format:

```
uwk_[52 character random string]
```

Example:

```
uwk_DlbWVU3Vjd11Le43kka6enGNjyd6xtbrBkNHMngl2aNz2Cm7
```

<Warning>
  API keys are sensitive credentials. Keep them secure and never expose them in client-side code or public repositories.
</Warning>

## Security Features

### Key Hashing

API keys are hashed using SHA-256 before storage. The plaintext key is only shown once upon creation.

### IP Whitelisting

Keys can be restricted to specific IP addresses for enhanced security.

### Expiration

All keys have an expiration date. Expired keys are automatically rejected.

### Scoped Permissions

Each key has granular permissions:

* **Read Balance**: Query merchant wallet balance
* **Read Transactions**: View payment history
* **Perform Operations**: Create payout operations

### Transaction Limits

Keys can have per-transaction and daily volume limits.

## Error Responses

<ResponseExample>
  ```json 401 Unauthorized - Missing or Invalid Key theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid or missing API key"
  }
  ```

  ```json 401 Unauthorized - Expired Key theme={null}
  {
    "error": "Unauthorized",
    "message": "API key has expired"
  }
  ```

  ```json 403 Forbidden - IP Not Allowed theme={null}
  {
    "error": "Forbidden",
    "message": "Request from unauthorized IP address"
  }
  ```

  ```json 403 Forbidden - Insufficient Permissions theme={null}
  {
    "type": "/problems/access-forbidden",
    "status": 403,
    "title": "Access Forbidden",
    "detail": "You do not have permission to perform this operation"
  }
  ```
</ResponseExample>

## Best Practices

<AccordionGroup>
  <Accordion title="Use Environment Variables">
    Store API keys in environment variables, never hard-code them:

    ```javascript theme={null}
    const apiKey = process.env.UNIVERSAL_WALLET_API_KEY;
    ```
  </Accordion>

  <Accordion title="Rotate Keys Regularly">
    Create new keys and revoke old ones every 90-180 days to minimize risk.
  </Accordion>

  <Accordion title="Use Minimum Required Permissions">
    Only enable the permissions your integration actually needs.
  </Accordion>

  <Accordion title="Monitor Key Usage">
    Regularly review API key usage logs for unexpected activity.
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Creating API Keys" icon="key" href="/merchants/api-tutorials/api-keys">
    Learn how to create and manage API keys
  </Card>

  <Card title="Security Best Practices" icon="shield" href="/concepts/security">
    Comprehensive security guide
  </Card>
</CardGroup>