API Keys

Learn how to generate, manage, and use API keys for SoshiaConnect API access.

What are API Keys?

API keys are authentication credentials that allow your applications to access the SoshiaConnect API without requiring user login. They're ideal for:

• Server-to-server communication
• Automated processes
• Third-party integrations
• Background jobs
• Scheduled tasks

API Keys vs Bearer Tokens

Feature	API Keys	Bearer Tokens
Use Case	Server-side applications	User-authenticated requests
Lifespan	Permanent (until revoked)	Expires after 24 hours
Refresh	Not required	Use /auth/refresh
Best For	Automation, integrations	Web/mobile apps
Security	Store in environment variables	Can be stored in memory

Creating API Keys

Via Portal

1. Log in to SoshiaConnect Portal
2. Navigate to API Keys section
3. Click Generate New API Key
4. Enter:
   • API Key Name: Descriptive name (e.g., "Production Server")
   • Username: Associated username for tracking
5. Click Generate
6. Copy and save the API key immediately - you won't see it again!

Via API

POST /api-keys/generate
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "api_key_name": "Production API Key",
  "user": "api_user_prod"
}

Response:

{
  "id": 1,
  "api_key_name": "Production API Key",
  "api_key": "sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
  "user": "api_user_prod",
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z"
}

Using API Keys

Header Format

GET /api-routes-data?id=123 HTTP/1.1
Host: api.soshiaconnect.com
X-API-Key: your_api_key_here
X-Username: your_username

Code Examples

JavaScript:

const axios = require('axios');

const config = {
  headers: {
    'X-API-Key': process.env.SOSHIA_API_KEY,
    'X-Username': process.env.SOSHIA_USERNAME
  }
};

axios.get('https://api.soshiaconnect.com/api/api-routes-data?id=123', config)
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

Python:

import requests
import os

headers = {
    'X-API-Key': os.getenv('SOSHIA_API_KEY'),
    'X-Username': os.getenv('SOSHIA_USERNAME')
}

response = requests.get(
    'https://api.soshiaconnect.com/api/api-routes-data',
    params={'id': 123},
    headers=headers
)
print(response.json())

PHP:

<?php
$apiKey = getenv('SOSHIA_API_KEY');
$username = getenv('SOSHIA_USERNAME');

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.soshiaconnect.com/api/api-routes-data?id=123');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: $apiKey",
    "X-Username: $username"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Managing API Keys

Listing All Keys

Via Portal: Navigate to API Keys section to see all your keys

Via API:

GET /api-keys
Authorization: Bearer YOUR_TOKEN

Viewing Key Details

GET /api-keys/{api_key_id}
Authorization: Bearer YOUR_TOKEN

Activating/Deactivating Keys

PUT /api-keys/{api_key_id}/status
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "status": "inactive"  // or "active"
}

Deleting Keys

DELETE /api-keys/{api_key_id}
Authorization: Bearer YOUR_TOKEN

⚠️ Warning: Deletion is permanent and will immediately revoke access for applications using this key.

Exporting Keys List

GET /api-keys/export
Authorization: Bearer YOUR_TOKEN

Returns CSV file with all your API keys (except the key values themselves).

Security Best Practices

1. Storage

✅ Do:

• Store in environment variables
• Use secret management systems (AWS Secrets Manager, HashiCorp Vault)
• Encrypt in databases
• Use key management services

❌ Don't:

• Hard-code in source code
• Commit to version control
• Share via email or chat
• Store in client-side code
• Log API keys

2. Key Rotation

Recommended Schedule:

Development: Every 30 days
Staging: Every 60 days
Production: Every 90 days

Rotation Process:

1. Generate new key
2. Update applications with new key
3. Test thoroughly
4. Deactivate old key
5. Monitor for errors
6. Delete old key after grace period

3. Naming Conventions

Use descriptive names that include:

• Environment (prod/staging/dev)
• Application name
• Purpose
• Creation date

Examples:

• prod-api-server-main-2025-01
• staging-integration-test-2025-01
• dev-local-machine-john-2025-01

4. Access Control

• Create separate keys per application
• Use different keys for different environments
• Limit key permissions (if available)
• Monitor key usage regularly
• Revoke keys immediately if compromised

5. Monitoring

Track API key usage:

GET /api-usage-logs
Authorization: Bearer YOUR_TOKEN

Monitor for:

• Unusual traffic patterns
• Failed authentication attempts
• Unexpected IP addresses
• Off-hours access
• Spike in API calls

Troubleshooting

Common Issues

401 Unauthorized

{
  "success": false,
  "message": "Invalid or missing authentication"
}

Solutions:

• Verify key is correct
• Check key is active
• Ensure proper header format
• Verify username matches

403 Forbidden

{
  "success": false,
  "message": "Insufficient permissions"
}

Solutions:

• Check subscription is active
• Verify access to requested route
• Ensure account in good standing

Key Not Working After Creation

• Allow 1-2 minutes for propagation
• Clear any caches
• Verify you copied the complete key
• Check for leading/trailing spaces

API Key Limits

Plan	Max API Keys	Rate Limit	Storage
Free	2	60/hour	30 days
Professional	10	5,000/hour	90 days
Enterprise	Unlimited	Custom	Unlimited

FAQs

Q: Can I recover a deleted API key? A: No, deletion is permanent. You must generate a new key.

Q: Can I see my API key after creation? A: No, for security reasons it's only shown once. Generate a new one if lost.

Q: Do API keys expire? A: No, they remain valid until you revoke them. However, regular rotation is recommended.

Q: Can I use the same key across multiple applications? A: While possible, it's not recommended. Use separate keys for better security and tracking.

Q: What happens if my key is compromised? A: Immediately deactivate or delete it via the portal, then generate a new one.

Q: Can I limit what an API key can access? A: Currently, API keys have full account access. Granular permissions may be available in future updates.

Related Documentation

• Authentication Guide
• API Best Practices
• Rate Limits
• API Reference