Authentication

Learn how to authenticate with the Rynko API using API keys for generating documents programmatically.

Overview

Rynko uses API keys for authentication when generating documents programmatically. API keys allow you to generate documents without exposing your account credentials.

info

Important: API keys are specifically designed for programmatic API access (server-to-server). Email/password authentication with JWT tokens is only used by the web dashboard - it should NOT be used for external API access.

---

API Keys

What are API Keys?

API keys are secure tokens that authenticate your application when making requests to the Rynko API. They act as a password for programmatic access.

Key Features:

• Scoped Permissions: Limit what each key can do
• Revocable: Disable a key without changing your password
• Trackable: Monitor usage per key
• Expirable: Set expiration dates for enhanced security

---

Creating an API Key

Via Dashboard (Recommended)

1. Navigate to Settings → API Keys in the dashboard
2. Click Create API Key
3. Configure the key:
   • Name: Descriptive name (e.g., "Production Server", "Dev Environment")
   • Permissions: Select what this key can do (generate documents, read templates, etc.)
   • Expiration: Optional expiry date (recommended for security)
4. Click Create Key
5. IMPORTANT: Copy the key immediately - it won't be shown again

API Key Format: fm_abc123xyz456def789...

---

Using API Keys

Authorization Header

Include your API key in the Authorization header with the Bearer scheme:

curl https://api.rynko.dev/api/v1/documents/generate \
  -H "Authorization: Bearer fm_abc123xyz456..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "templateId": "invoice-template",
    "format": "pdf",
    "variables": { "invoiceNumber": "INV-001", "customerName": "Acme Corp" }
  }'

JavaScript Example

const apiKey = 'fm_abc123xyz456...';

const response = await fetch('https://api.rynko.dev/api/v1/documents/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    templateId: 'invoice-template',
    format: 'pdf',
    variables: {
      invoiceNumber: 'INV-001',
      customerName: 'Acme Corp',
      total: 1500.00
    }
  })
});

const data = await response.json();
console.log('Document generated:', data.downloadUrl);

Python Example

import requests

api_key = 'fm_abc123xyz456...'
url = 'https://api.rynko.dev/api/v1/documents/generate'

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

payload = {
    'templateId': 'invoice-template',
    'format': 'pdf',
    'variables': {
        'invoiceNumber': 'INV-001',
        'customerName': 'Acme Corp',
        'total': 1500.00
    }
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print('Document generated:', data['downloadUrl'])

---

What Can API Keys Access?

API keys provide access to document generation and related operations:

Available Endpoints

Endpoint	Description	Documentation
POST /api/v1/documents/generate	Generate single document	Generating Documents
POST /api/v1/documents/generate/batch	Generate batch of documents	Generating Documents
GET /api/v1/documents/jobs/:id	Get job status	Documents API
GET /api/v1/templates	List templates	Templates API

warning

Permissions: API keys have limited permissions for security. They can generate documents using existing templates but cannot:

• Create or modify templates (dashboard only)
• Access billing settings (dashboard only)
• Manage project members (dashboard only)

This ensures that even if an API key is compromised, attackers cannot modify your templates or access sensitive data.

---

API Key Format

API keys use the format fm_{random_string}:

• Prefix: fm_
• Random String: Cryptographically secure identifier
• Best Practice: Store securely, rotate regularly

---

Security Best Practices

1. Keep Keys Secret

✅ DO:

• Store keys in environment variables
• Use secret management services (AWS Secrets Manager, HashiCorp Vault)
• Rotate keys regularly (every 90 days)

❌ DON'T:

• Commit keys to version control
• Hardcode keys in client-side code
• Share keys via email or chat

2. Use Environment Variables

# .env file (add to .gitignore)
RYNKO_API_KEY=fm_abc123xyz456...

// JavaScript
const apiKey = process.env.RYNKO_API_KEY;

# Python
import os
api_key = os.environ.get('RYNKO_API_KEY')

3. Limit Permissions

Grant the minimum permissions needed:

{
  "name": "Document Generator Service",
  "permissions": {
    "generate_documents": true,
    "read_templates": true
  },
  "expiresAt": "2025-12-31T23:59:59Z"
}

4. Set Expiration Dates

Always set an expiration date for long-lived keys:

{
  "name": "Q4 Report Generator",
  "permissions": {
    "generate_documents": true,
    "read_templates": true
  },
  "expiresAt": "2025-12-31T23:59:59Z"
}

5. Monitor Usage

Regularly review API key usage in the dashboard:

• Check for unexpected activity
• Monitor request volume
• Review permission usage

6. Rotate Keys

Implement key rotation:

1. Create a new API key
2. Update your application with the new key
3. Test thoroughly
4. Delete the old key

---

Error Handling

Invalid API Key

Status Code: 401 Unauthorized

{
  "statusCode": 401,
  "code": "ERR_AKEY_002",
  "message": "Invalid API key",
  "timestamp": "2025-11-07T10:30:00.000Z",
  "path": "/api/v1/documents/generate"
}

Deactivated API Key

Status Code: 401 Unauthorized

{
  "statusCode": 401,
  "code": "ERR_AKEY_003",
  "message": "API key has been deactivated",
  "timestamp": "2025-11-07T10:30:00.000Z",
  "path": "/api/v1/documents/generate"
}

Insufficient Permissions

Status Code: 403 Forbidden

{
  "statusCode": 403,
  "code": "ERR_AUTH_005",
  "message": "You do not have permission to perform this action",
  "timestamp": "2025-11-07T10:30:00.000Z",
  "path": "/api/v1/templates/create",
  "relatedInfo": {
    "required": "manage_templates",
    "granted": { "generate_documents": true, "read_templates": true }
  }
}

---

Rate Limiting

API requests are subject to rate limits based on the authentication type:

Authentication Type	Requests per Minute
API Key	100
OAuth	120
JWT (Dashboard)	200
Unauthenticated	30

See Rate Limiting for details.

---

Managing API Keys

All API key management operations are performed through the dashboard at Settings → API Keys.

Available operations:

• View all keys: See all active and expired keys
• Create new key: Generate a new API key
• View key details: Check creation date, last used, and expiration
• Revoke key: Immediately disable a key
• Set expiration: Add or update expiration date

info

Dashboard-Only: For security reasons, API key management is not available via API keys themselves. Use the dashboard to create, view, and revoke keys.

---

Common Questions

How many API keys can I create?

There's no limit on the number of API keys you can create. We recommend creating separate keys for each environment and service.

What happens if my key is compromised?

Immediately revoke the compromised key in the dashboard. Create a new key with different permissions and update your applications.

Can I use the same key in multiple environments?

While possible, it's not recommended. Use separate keys for development, staging, and production environments.

Do API keys expire automatically?

Only if you set an expiration date. Keys without an expiration date remain active until manually revoked.

Can I recover a deleted API key?

No, deleted keys cannot be recovered. You'll need to create a new key.

---

Related: Generating Documents | Error Handling | Rate Limiting