Skip to content

docs(authentication): simplify auth guide with API key vs Client ID methods and remove AI-generated content #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aimensahnoun wants to merge 1 commit into
base: 03-02-docs_api-features_rebuild_fee-breakdowns_with_api-accurate_fee_models_rewrite_api-features_fee-breakdowns.mdx_into_a_reconciliation-oriented_reference_that_reflects_actual_api_fee_fields_and_response_shapes._-_remove_ai-generate
Choose a base branch
from
+70 −221
Open

docs(authentication): simplify auth guide with API key vs Client ID methods and remove AI-generated content #70

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
291 changes: 70 additions & 221 deletions api-reference/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,243 +1,92 @@
---
title: "Authentication"
description: "API authentication, key management, and security best practices"
description: "How to authenticate Request Network API calls with API keys or Client ID"
---

<Warning>
**AI-Generated Content** – This page was generated with AI assistance and may contain inaccuracies. While likely close to accurate, please verify critical details with the [stable documentation](https://docs.request.network) or [contact support](https://github.com/orgs/RequestNetwork/discussions).
</Warning>

## Authentication Overview

Request Network API uses API key authentication to secure access to endpoints. This guide covers how to obtain, manage, and use your API keys securely.

## Getting API Keys

<Steps>
<Step title="Create Account">
Sign up for a Request Network account at the [Request Portal](https://portal.request.network)
</Step>
<Step title="Generate API Key">
Navigate to the API Keys section and create a new API key for your project
</Step>
<Step title="Configure Environment">
Store your API key securely in environment variables
</Step>
<Step title="Test Connection">
Make your first authenticated API call to verify setup
</Step>
</Steps>

## API Key Management

<CardGroup cols={2}>
<Card title="Production Keys" icon="shield">
**Production Environment:**
- Use separate keys for production
- Implement key rotation policies
- Monitor usage and access logs
- Set up rate limiting and alerts
</Card>

<Card title="Development Keys" icon="code">
**Development Environment:**
- Use testnet for development
- Separate keys for each environment
- Team access management
- Testing and debugging tools
</Card>
</CardGroup>
## Overview

## Authentication Methods

<Tabs>
<Tab title="Header Authentication">
**API Key in Header (Recommended):**

```bash
curl -X POST https://api.request.network/v2/requests \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"currency": "USD",
"expectedAmount": "100",
"payeeIdentity": "0x...",
"reason": "Test invoice"
}'
```

<Info>
**Optional Headers:**
- `x-client-id`: Your client identifier for request tracking
- `Origin`: Required for browser-based requests (CORS)
</Info>
</Tab>

<Tab title="Environment Variables">
**Secure Key Storage:**

```javascript
// .env file
REQUEST_NETWORK_GATEWAY_URL=https://sepolia.gateway.request.network/

// Application code
import { RequestNetwork } from '@requestnetwork/request-client.js';
import { EthereumPrivateKeySignatureProvider } from '@requestnetwork/epk-signature';

const signatureProvider = new EthereumPrivateKeySignatureProvider({
method: Types.SIGNATURE_METHOD.ECDSA,
privateKey: process.env.PRIVATE_KEY
});

const requestNetwork = new RequestNetwork({
nodeConnectionConfig: {
baseURL: process.env.REQUEST_NETWORK_GATEWAY_URL
},
signatureProvider
});
```
</Tab>

<Tab title="SDK Configuration">
**SDK Authentication:**

```javascript
import { RequestNetwork, Types } from '@requestnetwork/request-client.js';
import { EthereumPrivateKeySignatureProvider } from '@requestnetwork/epk-signature';

const signatureProvider = new EthereumPrivateKeySignatureProvider({
method: Types.SIGNATURE_METHOD.ECDSA,
privateKey: process.env.PRIVATE_KEY
});

const requestNetwork = new RequestNetwork({
nodeConnectionConfig: {
baseURL: 'https://sepolia.gateway.request.network/'
},
signatureProvider
});
```
</Tab>
</Tabs>

## Security Best Practices

<AccordionGroup>
<Accordion title="API Key Security">
**Protect Your API Keys:**
- Never commit API keys to version control
- Use environment variables for key storage
- Implement key rotation policies
- Monitor for unauthorized usage
- Use different keys for different environments
</Accordion>

<Accordion title="Network Security">
**Secure Communication:**
- Always use HTTPS for API calls
- Implement request signing for sensitive operations
- Use webhook signature verification
- Implement rate limiting on your endpoints
</Accordion>

<Accordion title="Access Control">
**Manage Access:**
- Use principle of least privilege
- Implement role-based access control
- Regular access audits
- Immediate revocation of compromised keys
</Accordion>
</AccordionGroup>

## Rate Limits
Request Network API supports two authentication modes:

<Info>
**Rate Limiting Information**
- `x-api-key` for server-side integrations
- `x-client-id` for browser/client integrations (with `Origin` header)

Current rate limits apply to API usage. Contact support for enterprise rate limit increases.
</Info>
Use this page as the canonical auth reference. For credential creation and webhook setup in the portal, see [API Portal: Manage API Keys and Webhooks](/request-network-api/api-portal-manage-api-keys-and-webhooks).

<CardGroup cols={2}>
<Card title="Standard Limits" icon="clock">
**Default Rate Limits:**
- 100 requests per minute
- 1,000 requests per hour
- 10,000 requests per day

**Applies to:** Most API endpoints
</Card>

<Card title="Webhook Limits" icon="webhook">
**Webhook Rate Limits:**
- 50 webhook deliveries per minute
- Exponential backoff for retries
- Maximum 5 retry attempts

**Applies to:** Webhook delivery endpoints
</Card>
</CardGroup>
## Choose the Right Method

## Error Codes
| Method | Best for | Header(s) |
| --- | --- | --- |
| API Key | Backend services, cron jobs, trusted server environments | `x-api-key` |
| Client ID | Browser/front-end calls where client auth is required | `x-client-id` (+ `Origin`) |

Common authentication error responses:
## API Key Authentication

<CodeGroup>
```json 401 Unauthorized
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key",
"details": "Please provide a valid API key in the Authorization header"
}
}
```
Use API keys for backend calls.

### Example

```json 403 Forbidden
{
"error": {
"code": "FORBIDDEN",
"message": "API key does not have required permissions",
"details": "This operation requires additional permissions"
}
}
```bash cURL
curl -X GET 'https://api.request.network/v2/request/{requestId}' \
-H 'x-api-key: YOUR_API_KEY'
```

```json 429 Rate Limited
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded",
"details": "Too many requests. Please try again later.",
"retryAfter": 60
}
}
## Client ID Authentication

Use Client ID when your integration needs browser-side authentication flow.

### Example

```bash cURL
curl -X GET 'https://api.request.network/v2/request/{requestId}' \
-H 'x-client-id: YOUR_CLIENT_ID' \
-H 'Origin: https://your-app.example'
```
</CodeGroup>

## What's Next?
<Info>
For browser-based requests, `Origin` is part of the request context and is required for Client ID auth.
</Info>

## Header Reference

- `x-api-key`: API key used for server-side auth
- `x-client-id`: Client identifier used for client-side auth
- `Origin`: required with Client ID flows in browser contexts

## Common Authentication Errors

### 401 Unauthorized

- Missing auth header
- Invalid/expired API key or client ID

### 403 Forbidden

- Credentials are valid but not allowed for the requested operation
- Client ID is revoked or restricted

### 429 Too Many Requests

- Request rate exceeded for your credentials

## Security Guidance

- Keep API keys server-side and out of frontend bundles
- Store credentials in environment variables or secret managers
- Rotate compromised credentials immediately
- Verify webhook signatures independently (webhook signing uses a separate secret)

## Related Pages

<CardGroup cols={3}>
<Card
title="🔗 Webhooks"
href="/api-reference/webhooks"
icon="webhook"
>
Set up real-time event notifications
<Card title="API Portal" href="/request-network-api/api-portal-manage-api-keys-and-webhooks" icon="key">
Create credentials and manage webhook configuration.
</Card>

<Card
title="🛠️ Create Request"
href="/request-network-api/create-and-pay-requests"
icon="plus"
>
Make your first API call

<Card title="Webhooks" href="/api-reference/webhooks" icon="webhook">
Signature verification and delivery behavior.
</Card>

<Card
title="🔑 API Portal"
href="/api-setup/getting-started"
icon="key"
>
Manage your API keys and settings

<Card title="OpenAPI Reference" href="https://api.request.network/open-api" icon="book">
Full endpoint authentication requirements.
</Card>
</CardGroup>