IK
InnKeeperAPI Docs

Authentication Guide

The InnKeeper API supports two authentication methods: API Keys (simple) and OAuth 2.0 JWT (recommended for production).

API Key Authentication

API keys are the simplest way to authenticate. Best for testing, simple integrations, and server-to-server communication.

Getting an API Key

Contact your InnKeeper account manager or email api@innkeeper.africa with:

  • Your organization name
  • Entity ID
  • Intended use case
  • Environment (development/production)

You'll receive:

API Key: sk_live_abcd1234efgh5678

Using API Keys

Include your API key in the x-app-key header:

curl https://xyz.convex.site/api/v1/task-manager/requests \
  -H "x-app-key: sk_live_abcd1234efgh5678" \
  -H "Content-Type: application/json"

In Code:

Node.js / JavaScript

const response = await fetch('https://xyz.convex.site/api/v1/task-manager/requests', {
  headers: {
    'x-app-key': 'sk_live_abcd1234efgh5678',
    'Content-Type': 'application/json'
  }
});

Python

import requests

response = requests.get(
    'https://xyz.convex.site/api/v1/task-manager/requests',
    headers={'x-app-key': 'sk_live_abcd1234efgh5678'}
)

API Key Best Practices

✅ DO:

  • Store keys in environment variables
  • Use different keys for dev/staging/prod
  • Rotate keys regularly (every 90 days)
  • Use premium keys for production

❌ DON'T:

  • Commit keys to version control
  • Share keys between applications
  • Use production keys in development
  • Expose keys in client-side code

OAuth 2.0 Authentication

OAuth 2.0 provides enhanced security with automatic token refresh and fine-grained access control. Recommended for production integrations.

OAuth 2.0 Flow

InnKeeper uses the Client Credentials flow:

  1. Your App → InnKeeper: Request access token
  2. InnKeeper → Your App: Return JWT access token
  3. Your App → InnKeeper API: Use token in Authorization header
  4. Token expires after 1 hour → Refresh automatically

Getting OAuth Credentials

Contact api@innkeeper.africa to register your application. You'll receive:

Client ID: innkeeper_client_abc123
Client Secret: secret_xyz789 (keep this secure!)
Token URL: https://auth.innkeeper.africa/oauth/token
Audience: innkeeper-api

Obtaining an Access Token

curl -X POST https://auth.innkeeper.africa/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "innkeeper_client_abc123:secret_xyz789" \
  -d "grant_type=client_credentials&scope=task:read task:write property:read property:write"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "task:read task:write property:read property:write"
}

Using OAuth Tokens

Include the token in the Authorization header:

curl https://xyz.convex.site/api/v1/task-manager/requests \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

OAuth Scopes

Request only the scopes you need:

ScopeDescription
task:readRead service requests and tasks
task:writeCreate and update requests/tasks
property:readRead rooms, housekeeping reports
property:writeUpdate room status, create reports
webhook:receiveReceive webhook notifications
admin:*Full administrative access

Security Best Practices

Storing Credentials

Always use environment variables:

# .env file (never commit this!)
INNKEEPER_CLIENT_ID=innkeeper_client_abc123
INNKEEPER_CLIENT_SECRET=secret_xyz789
INNKEEPER_API_KEY=sk_live_abcd1234efgh5678

⚠️ Security Warning: Consider using secret management services like AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault for production environments.

HTTPS Only

Always use HTTPS in production:

✅ https://xyz.convex.site

❌ http://xyz.convex.site

Rotate Credentials

  • API Keys: Every 90 days
  • OAuth Secrets: Every 180 days
  • Set calendar reminders
  • Implement graceful rotation (overlap period)

Troubleshooting

401 Unauthorized - Invalid API Key

Error: "Invalid API key"

Solutions:

  • Verify API key is correct (no extra spaces)
  • Check key hasn't been revoked
  • Ensure using x-app-key header
  • Verify environment (dev key won't work in prod)

401 Unauthorized - Token Expired

Error: "Token has expired"

Solutions:

  • Implement automatic token refresh
  • Check system clock is synchronized (NTP)
  • Request new token before 2-minute expiry buffer

403 Forbidden - Insufficient Scopes

Error: "Insufficient permissions"

Solutions:

  • Request additional scopes when getting token
  • Check scope string format (space-separated)
  • Contact support to enable scope for your account

Next Steps

🔔 Webhook Setup

Configure Oracle event notifications

📚 API Reference

Explore all endpoints

InnKeeper API Documentation | InnKeeper