Authentication

Overview

The Oquira Business API uses API Keys for server-to-server integrations and Session Tokens for dashboard-like client applications. This page explains how to use each method securely.

API Keys

API keys are the recommended way to authenticate your backend servers. They provide secure, long-lived access to the API.

Getting Your API Keys

1. Log in to the Oquira Business
2. Navigate to Settings > API Keys
3. Click Generate New Key
4. Select the appropriate scopes (permissions)
5. Copy and securely store your key

Important: API keys are shown only once. Store them securely immediately after creation.

Using API Keys

You should provide your API key using the X-API-Key header:

curl -X GET "https://api.oquira.com/v1/business/services" \
  -H "X-API-Key: your_api_key_here"

Example Request

curl -X GET "https://api.oquira.com/v1/business/services" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

API Key Scopes

When creating an API key, you can limit its permissions:

Session-Based Authentication

For client-side applications (like custom dashboards), you can use session-based authentication.

Login

Authenticate a user and receive a session:

curl -X POST "https://api.oquira.com/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@yourbusiness.com",
    "password": "yourpassword"
  }'

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "clsh8b4c5000308l2bh3z6p9k",
      "email": "admin@yourbusiness.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "role": "admin",
      "accountType": "business"
    },
    "session": {
      "token": "sess_clsh8n4p5000708l2bh3z6p9k",
      "expiresAt": "2024-03-22T10:00:00.000Z"
    }
  }
}

Using the Session

Web clients should use the better-auth.session_token cookie for subsequent requests. The cookie is automatically set after a successful login.

For API access with sessions:

curl -X GET "https://api.oquira.com/v1/business/dashboard" \
  -H "Cookie: better-auth.session_token=sess_xyz789..."

Session Refresh

Sessions expire after a period of inactivity. To keep the session alive:

curl -X POST "https://api.oquira.com/v1/auth/session/refresh" \
  -H "Cookie: better-auth.session_token=sess_xyz789..."

Logout

End a session explicitly:

curl -X POST "https://api.oquira.com/v1/auth/logout" \
  -H "Cookie: better-auth.session_token=sess_xyz789..."

Security Best Practices

Key Management

• Never expose API keys in client-side code (browsers, mobile apps)
• Use environment variables to store keys in your applications
• Rotate keys periodically, especially after team members leave
• Use separate keys for different services or applications

Environment Separation

• Use separate keys for development vs production environments to prevent accidental data modification.

Access Control

• Limit key scopes to only the permissions necessary
• Monitor API usage in your dashboard for unusual activity
• Set up alerts for failed authentication attempts

Key Rotation

If you suspect a key has been compromised:

1. Go to Settings > API Keys in your dashboard
2. Generate a new key with the same scopes
3. Update your applications with the new key
4. Revoke the old key once the transition is complete

Error Responses

Authentication errors return standard error responses:

Example Error Response

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or expired API key",
    "timestamp": "2024-03-20T10:00:00.000Z",
    "requestId": "req_5f2b8c9d1e"
  }
}

Next Steps

• Getting Started - Make your first API call
• Responses - Learn about response formats
• Errors - Handle errors in your integration
• Rate Limits - Understand API usage limits