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

# API Keys

> Create and manage API keys for Meridian x402 payment APIs

## Overview

API keys are required to authenticate Meridian x402 payment API requests. They provide secure, programmatic access to Meridian's payment infrastructure for your applications.

## Key Types

Meridian Protocol uses **public keys** for API authentication:

* **Public Key (pk\_)**: Used for API authentication
* **Test Mode Keys**: Prefixed with `pk_test_` for development
* **Production Keys**: Prefixed with `pk_` for live transactions

<Note>
  Secret keys are generated but only shown once during creation for security.
  The public key is used for all API requests.
</Note>

## Creating API Keys

### Via Developer Dashboard

<Steps>
  <Step title="Sign in with Ethereum">
    Connect your wallet and authenticate using SIWE
  </Step>

  <Step title="Navigate to API Keys">
    Go to the API Keys section in your developer dashboard
  </Step>

  <Step title="Create New Key">
    Click "Create API Key" and provide a descriptive name
  </Step>

  <Step title="Choose Environment">
    Select test mode for development or production for live transactions
  </Step>

  <Step title="Save Your Keys">
    Copy and securely store both keys - the secret is only shown once!
  </Step>
</Steps>

### Via API

You can also create API keys programmatically:

```bash theme={"system"}
curl -X POST https://api.mrdn.finance/v1/api_keys \
  -H "Content-Type: application/json" \
  -H "Cookie: siwe-session=your_session" \
  -d '{
    "name": "My Application Key",
    "test_net": true
  }'
```

**Response:**

```json theme={"system"}
{
  "id": "key_1234567890abcdef",
  "name": "My Application Key",
  "organization": "org_456",
  "api_key": "pk_test_1234567890abcdef...",
  "api_secret_key": "sk_test_abcdef1234567890...",
  "test_net": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}
```

<Warning>
  The `api_secret_key` is only returned once during creation. Store it securely!
</Warning>

## Using API Keys

### Authentication Header

Include your public key in the Authorization header:

<Warning>
  `POST /v1/verify` is deprecated. Use `POST /v1/settle` for current API
  examples and new integrations.
</Warning>

```bash theme={"system"}
curl -X POST https://api.mrdn.finance/v1/settle \
  -H "Authorization: Bearer pk_1234567890abcdef..." \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": {...},
    "paymentRequirements": {...}
  }'
```

### JavaScript/Node.js

```javascript theme={"system"}
const apiKey = "pk_test_1234567890abcdef...";

const response = await fetch("https://api.mrdn.finance/v1/settle", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    paymentPayload: {
      /* ... */
    },
    paymentRequirements: {
      /* ... */
    },
  }),
});
```

### Python

```python theme={"system"}
import requests

api_key = 'pk_test_1234567890abcdef...'
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.mrdn.finance/v1/settle',
    headers=headers,
    json={
        'paymentPayload': { /* ... */ },
        'paymentRequirements': { /* ... */ }
    }
)
```

## Managing API Keys

### List All Keys

```bash theme={"system"}
curl https://api.mrdn.finance/v1/api_keys \
  -H "Cookie: siwe-session=your_session"
```

**Response:**

```json theme={"system"}
{
  "apiKeys": [
    {
      "id": "key_1234567890abcdef",
      "name": "My Application Key",
      "organization": "org_456",
      "api_key": "pk_test_1234567890abcdef...",
      "test_net": true,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z",
      "last_used_at": "2024-01-01T12:00:00.000Z"
    }
  ]
}
```

### Get Single Key

```bash theme={"system"}
curl https://api.mrdn.finance/v1/api_keys/key_1234567890abcdef \
  -H "Cookie: siwe-session=your_session"
```

## Test vs Production Keys

### Test Mode Keys (`pk_test_`)

* Used for development and testing
* Process payments on testnets (Base Sepolia, etc.)
* No real money involved
* Separate analytics and transaction history

### Production Keys (`pk_`)

* Used for live applications
* Process real payments on mainnets
* Handle actual value transfers
* Production-level monitoring and support

<Tip>
  Always use test keys during development. Switch to production keys only when
  your integration is complete and tested.
</Tip>

## Security Best Practices

### Key Storage

* **Never** commit API keys to version control
* Use environment variables or secure key management services
* Rotate keys regularly
* Use different keys for different environments

### Access Control

* API keys are scoped to your organization
* Each key tracks usage and last access time
* Keys can be individually managed and revoked

### Environment Variables

```bash theme={"system"}
# .env file
MERIDIAN_API_KEY=pk_test_1234567890abcdef...

# In your application
const apiKey = process.env.MERIDIAN_API_KEY
```

## API Key Endpoints

<CardGroup cols={2}>
  <Card title="Create API Key" icon="plus">
    `POST /v1/api_keys` - Create a new API key pair
  </Card>

  <Card title="List API Keys" icon="list">
    `GET /v1/api_keys` - Get all keys for your organization
  </Card>

  <Card title="Get API Key" icon="eye">
    `GET /v1/api_keys/:id` - Get details for a specific key
  </Card>

  <Card title="Delete API Key" icon="trash">
    `DELETE /v1/api_keys/:id` - Delete an API key
  </Card>
</CardGroup>

## Troubleshooting

### Common Errors

**401 Unauthorized**

* Check that your API key is correct
* Ensure you're using the right environment (test vs production)
* Verify the Authorization header format: `Bearer pk_...`

**403 Forbidden**

* API key may be revoked or expired
* Check if you're accessing the correct organization's resources

### Testing Your API Key

```bash theme={"system"}
# Test authentication
curl https://api.mrdn.finance/v1/supported \
  -H "Authorization: Bearer pk_test_your_key_here"

# Should return supported payment kinds
{
  "kinds": [
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "base-sepolia"
    }
  ]
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Settle Payments" icon="shield-check" href="/api-reference/endpoint/settle-payment">
    Start settling x402 payments with your API key
  </Card>

  <Card title="View Transactions" icon="list" href="/command-centre/transactions">
    Monitor your payment transactions
  </Card>

  <Card title="Get Analytics" icon="chart-line" href="/command-centre/analytics">
    Access detailed payment analytics
  </Card>

  <Card title="Developer Dashboard" icon="gauge" href="https://mrdn.finance/dev/api-keys">
    Manage keys in the web interface
  </Card>
</CardGroup>