Official Optare CLI Integration Guide

Date: November 15, 2025
Status: ✅ Production Ready
Base URL: https://id.optare.one (Single Domain - No Subdomains)

📋 Table of Contents

🎯 Overview

The Optare CLI automation system integrates with id.optare.one (single domain) to provide:

Automated Product Management - Create and manage products programmatically
Subscription Management - Automate subscription creation and updates
OAuth 2.0 Integration - Secure client app authentication
Admin Portal - Manage products, subscriptions, and clients
Client Portal - Users authorize apps and manage access

🏗️ Architecture

System Components

┌─────────────────────────────────────────────────────────────┐
│                    id.optare.one                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │           OAuth 2.0 Endpoints                        │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  • /oauth/authorize    - Authorization endpoint     │  │
│  │  • /oauth/token        - Token endpoint             │  │
│  │  • /oauth/userinfo     - User info endpoint         │  │
│  │  • /.well-known/openid-configuration               │  │
│  │  • /.well-known/jwks.json                           │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │           API Endpoints                              │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  • /api/v1/users/me    - Current user info         │  │
│  │  • /api/v1/licenses/check - License verification    │  │
│  │  • /api/v1/subscriptions - Subscription info    │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │           Admin Portal                               │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  • /admin/dashboard    - Admin dashboard            │  │
│  │  • /admin/products     - Product management UI      │  │
│  │  • /admin/subscriptions - Subscription UI           │  │
│  │  • /admin/clients      - OAuth client management    │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │           Client Portal                              │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  • /portal/dashboard   - User dashboard             │  │
│  │  • /portal/oauth-clients - Connected apps           │  │
│  │  • /portal/subscriptions - User subscriptions       │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

🔐 OAuth 2.0 Integration

Overview

Optare uses OAuth 2.0 with OpenID Connect (OIDC) for secure client authentication.

Base URL: https://id.optare.one

Endpoints

1. Authorization Endpoint

Parameters:

client_id (required) - Your OAuth client ID
redirect_uri (required) - Where to redirect after authorization
response_type (required) - Must be code
scope (required) - Space-separated scopes
state (recommended) - CSRF protection
code_challenge (optional) - PKCE code challenge
code_challenge_method (optional) - S256 or plain

Example:

https://id.optare.one/oauth/authorize?
  client_id=client_abc123&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=openid+email+profile+otomate-social-pro&
  state=random_state_value&
  code_challenge=E9Mrozoa2owUednMEfp_rZxsIrxVArokAZd3KeKT9A&
  code_challenge_method=S256

2. Token Endpoint

Request Body (form-urlencoded):

grant_type=authorization_code&
code=<authorization_code>&
client_id=<client_id>&
client_secret=<client_secret>&
redirect_uri=<redirect_uri>&
code_verifier=<code_verifier>

Response:

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_...",
  "scope": "openid email profile otomate-social-pro"
}

3. UserInfo Endpoint

Authorization: Bearer <access_token>

Response:

{
  "sub": "user_123",
  "email": "user@example.com",
  "email_verified": true,
  "name": "John Doe",
  "organizationId": "org_123",
  "products": [
    {
      "id": "prod_123",
      "slug": "otomate-social-pro",
      "name": "Otomate Social - Pro",
      "features": ["Unlimited posts", "All platforms"]
    }
  ]
}

4. OpenID Configuration

Returns OIDC discovery document with all endpoints.

5. JWKS Endpoint

Returns public keys for JWT verification.

👨‍💼 Admin Workflows

1. Admin Dashboard Access

URL: https://id.optare.one/admin/dashboard

Requirements:

Admin or Owner role in organization
Active session

2. Create Products (UI)

Path: Admin Dashboard → Products → Create New

Steps:

Click "Create Product"
Enter product name
Enter product slug (unique identifier)
Add description
Add features
Click "Create"

Or via CLI:

pnpm optare:product:create -- \
  --name "Product Name" \
  --slug "product-slug" \
  --description "Description" \
  --features "Feature 1" "Feature 2"

3. Create Subscriptions (UI)

Path: Admin Dashboard → Subscriptions → Create New

Steps:

Select organization
Select product
Enter number of seats
Enter price per seat
Select billing cycle (monthly/yearly)
Select status (active/trial/cancelled/expired)
(Optional) Set end date
Click "Create"

Or via CLI:

pnpm optare:subscription:create -- \
  --organization "org_123" \
  --product "product-slug" \
  --seats 100 \
  --price 29.99 \
  --cycle monthly \
  --status active

4. Manage OAuth Clients

Path: Admin Dashboard → OAuth Clients

Capabilities:

View all registered OAuth clients
Create new OAuth client
Edit client details
Manage redirect URIs
Manage allowed origins
Manage allowed scopes
Enable/disable clients
View client credentials

Creating OAuth Client:

Click "Create New Client"
Enter application name
Enter application description
Add redirect URIs (where users return after auth)
Add allowed origins (for CORS)
Select allowed scopes
Click "Create"
Save client ID and secret securely

5. View Audit Logs

Path: Admin Dashboard → Audit Logs

Tracks:

Product creation/updates
Subscription changes
OAuth client management
User access changes
Admin actions

👥 Client Workflows

1. Client Portal Access

URL: https://id.optare.one/portal/dashboard

Requirements:

User account
Active session
Organization membership

2. View Subscriptions

Path: Client Portal → Subscriptions

Shows:

All active subscriptions
Product details
Seat count
Billing cycle
Status
Expiration date (if applicable)

3. Connect OAuth Applications

Path: Client Portal → Connected Apps

Steps:

Click "Connect New App"
Review permissions requested
Click "Authorize"
App receives authorization code
App exchanges code for access token
App can now access user data

What happens:

User is redirected to OAuth authorization endpoint
User reviews permissions
User grants or denies consent
User is redirected back to app with authorization code
App exchanges code for access token
App uses access token to access user data

4. Manage Connected Apps

Path: Client Portal → Connected Apps

Capabilities:

View all connected applications
See permissions granted
Revoke access to any app
View last access time
Remove app from account

5. View Product Access

Path: Client Portal → Products

Shows:

All products user has access to
Product features
Usage statistics
Product documentation links

📡 API Reference

Authentication

All API requests require authentication:

curl -H "Authorization: Bearer <access_token>" \
     https://id.optare.one/v1/products

Products API

List Products

Response:

{
  "products": [
    {
      "id": "prod_123",
      "name": "Product Name",
      "slug": "product-slug",
      "description": "Description",
      "features": ["Feature 1", "Feature 2"],
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}

Create Product

Content-Type: application/json

{
  "name": "Product Name",
  "slug": "product-slug",
  "description": "Description",
  "features": ["Feature 1", "Feature 2"]
}

Get Product

Subscriptions API

List Subscriptions

Create Subscription

Content-Type: application/json

{
  "organization_id": "org_123",
  "product_id": "prod_123",
  "total_seats": 100,
  "price_per_seat": 29.99,
  "billing_cycle": "monthly",
  "status": "active",
  "end_date": "2025-12-31T00:00:00Z"
}

Get Subscription

Update Subscription

PATCH /v1/subscriptions/{id}
Content-Type: application/json

{
  "total_seats": 150,
  "price_per_seat": 24.99,
  "status": "active",
  "end_date": "2025-12-31T00:00:00Z"
}

Cancel Subscription

PATCH /v1/subscriptions/{id}
Content-Type: application/json

{
  "status": "cancelled"
}

🔒 Security

API Key Management

Obtaining API Keys:

Login to https://id.optare.one/admin
Go to Settings → API Keys
Click "Create New Key"
Copy API Key and Secret
Store securely (never commit to git)

Best Practices:

Store in .env.local (not in code)
Rotate keys regularly
Use separate keys for different environments
Revoke unused keys
Monitor API key usage

OAuth Client Security

Client Secret Management:

Store securely (never expose in frontend)
Use environment variables
Rotate periodically
Revoke compromised secrets

PKCE (Proof Key for Code Exchange):

Recommended for all OAuth flows
Prevents authorization code interception
Required for mobile/SPA apps

Redirect URI Validation:

Only registered URIs are allowed
Prevents open redirect attacks
Validate on both client and server

Token Security

Access Token:

Valid for 1 hour
JWT format
Contains user and product information
Should be stored securely

Refresh Token:

Valid for 30 days
Used to obtain new access tokens
Should be stored securely
Rotated on each use

Session Management:

Session version tracked
Invalidates all tokens on password change
Prevents session hijacking

🔧 Integration Examples

Node.js / Express

import axios from 'axios';
 
const optareClient = axios.create({
  baseURL: 'https://id.optare.one',
  headers: {
    'Authorization': `Bearer ${process.env.OPTARE_API_KEY}`,
    'X-API-Secret': process.env.OPTARE_API_SECRET,
  },
});
 
// Create product
const product = await optareClient.post('/v1/products', {
  name: 'My Product',
  slug: 'my-product',
  features: ['Feature 1', 'Feature 2'],
});
 
// Create subscription
const subscription = await optareClient.post('/v1/subscriptions', {
  organization_id: 'org_123',
  product_id: product.data.id,
  total_seats: 100,
  price_per_seat: 29.99,
  billing_cycle: 'monthly',
  status: 'active',
});

OAuth Flow (Client App)

// 1. Redirect to authorization endpoint
const authUrl = new URL('https://id.optare.one/oauth/authorize');
authUrl.searchParams.set('client_id', CLIENT_ID);
authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'openid email profile');
authUrl.searchParams.set('state', generateRandomState());
 
window.location.href = authUrl.toString();
 
// 2. Handle callback
app.get('/callback', async (req, res) => {
  const { code, state } = req.query;
  
  // Verify state
  if (state !== storedState) {
    return res.status(400).send('Invalid state');
  }
  
  // Exchange code for token
  const response = await axios.post('https://id.optare.one/oauth/token', {
    grant_type: 'authorization_code',
    code,
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    redirect_uri: 'https://yourapp.com/callback',
  });
  
  const { access_token, refresh_token } = response.data;
  
  // Store tokens securely
  // Use access_token for API requests
});
 
// 3. Get user info
const userInfo = await axios.get('https://id.optare.one/oauth/userinfo', {
  headers: {
    'Authorization': `Bearer ${access_token}`,
  },
});

🐛 Troubleshooting

Common Issues

1. Invalid Client ID

Error: invalid_client: Client not found

Solution:

Verify client ID is correct
Check client is active in admin panel
Ensure client is registered for your organization

2. Redirect URI Mismatch

Error: invalid_request: redirect_uri not registered

Solution:

Verify redirect URI matches exactly
Check for trailing slashes
Ensure URI is registered in admin panel

3. Invalid Scope

Error: invalid_scope: Requested scope not allowed

Solution:

Verify scope is allowed for client
Check scope is spelled correctly
Ensure user has access to product

4. Token Expired

Error: invalid_token: Access token is invalid or expired

Solution:

Use refresh token to get new access token
Implement token refresh logic
Check token expiration time

5. Authorization Code Expired

Error: invalid_grant: Authorization code has expired

Solution:

Exchange code immediately (5 minute window)
Don't store code for later use
Implement proper error handling

📊 Monitoring & Logging

Admin Monitoring

Audit Logs: https://id.optare.one/admin/audit-logs

Tracks:

Product creation/updates
Subscription changes
OAuth client management
User access changes
Failed authentication attempts

API Monitoring

Rate Limits:

100 requests per minute per API key
1000 requests per hour per organization

Error Tracking:

Monitor 4xx errors (client errors)
Monitor 5xx errors (server errors)
Track failed OAuth flows

🚀 Deployment Checklist

✅ API keys obtained and stored securely
✅ OAuth client registered
✅ Redirect URIs configured
✅ Allowed scopes set
✅ Environment variables configured
✅ Error handling implemented
✅ Token refresh logic implemented
✅ Audit logging enabled
✅ Security headers configured
✅ Rate limiting implemented

📞 Support

Status: ✅ Production Ready
Last Updated: November 15, 2025
Base URL: https://id.optare.one (opens in a new tab) (Single Domain)

Getting Started Marketplace

Official Optare CLI Integration Guide

📋 Table of Contents

🎯 Overview

🏗️ Architecture

System Components

🔐 OAuth 2.0 Integration

Overview

Endpoints

1. Authorization Endpoint

2. Token Endpoint

3. UserInfo Endpoint

4. OpenID Configuration

5. JWKS Endpoint

👨‍💼 Admin Workflows

1. Admin Dashboard Access

2. Create Products (UI)

3. Create Subscriptions (UI)

4. Manage OAuth Clients

5. View Audit Logs

👥 Client Workflows

1. Client Portal Access

2. View Subscriptions

3. Connect OAuth Applications

4. Manage Connected Apps

5. View Product Access

📡 API Reference

Authentication

Products API

List Products

Create Product

Get Product

Subscriptions API

List Subscriptions

Create Subscription

Get Subscription

Update Subscription

Cancel Subscription

🔒 Security

API Key Management

OAuth Client Security

Token Security

🔧 Integration Examples

Node.js / Express

OAuth Flow (Client App)

🐛 Troubleshooting

Common Issues

1. Invalid Client ID

2. Redirect URI Mismatch

3. Invalid Scope

4. Token Expired

5. Authorization Code Expired

📊 Monitoring & Logging

Admin Monitoring

API Monitoring

🚀 Deployment Checklist

📞 Support

Documentation

Admin Portal

Client Portal