Prerequisites

An Operating account
A terminal or API client (we'll use cURL in these examples)
Basic familiarity with REST APIs

Step 1: Get your API key

API keys are managed per organization in Operating.

Log in to your Operating account at https://operating.app
Navigate to Settings → Integrations → API Keys
Click Create API Key
Give it a descriptive name (e.g., "Development Testing")
Copy the API key immediately — it won't be shown again

❗️
Each organization can have only one active API key at a time. Creating a new API key immediately invalidates any existing keys. If you have integrations using an old key, they will stop working when you create a new one.

❗️
Store your API key securely. Anyone with this key can access your organization's data. Never commit API keys to version control or share them in public channels.

Step 2: Test authentication

The Operating API uses Bearer token authentication. Every request must include your API key in the Authorization header.

Let's verify your API key works by fetching the list of companies in your organization:

curl https://api.operating.app/v1/companies \
  -H "Authorization: Bearer $OPERATING_API_KEY"

Replace $OPERATING_API_KEY with your actual API key, or export it as an environment variable:

export OPERATING_API_KEY="your_api_key_here"

Expected response:

{
  "items": [
    {
      "id": "1",
      "name": "Northwind Consulting Oy",
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z"
    }
  ],
  "cursor": null
}

If you see this structure, authentication is working.

Step 3: Fetch a list of projects

Now let's retrieve something more useful: your organization's projects.

curl https://api.operating.app/v1/projects \
  -H "Authorization: Bearer $OPERATING_API_KEY"

Expected response:

{
  "items": [
    {
      "id": "7001",
      "name": "Stellar Platform Modernization",
      "clientId": "4001",
      "billingType": "time-and-materials",
      "companyId": "1",
      "projectOwnerId": "1005",
      "estimatedStartDate": "2025-03-01",
      "estimatedEndDate": "2025-09-30",
      "createdAt": "2025-02-01T10:00:00Z",
      "updatedAt": "2025-02-01T10:00:00Z"
    },
    {
      "id": "7002",
      "name": "Atlas Risk Platform",
      "clientId": "4002",
      "billingType": "fixed-price",
      "revenueRecognitionMethod": "weighted-by-hours-and-rates",
      "companyId": "2",
      "projectOwnerId": "1005",
      "estimatedStartDate": "2025-04-01",
      "estimatedEndDate": "2025-12-31",
      "createdAt": "2025-03-15T14:30:00Z",
      "updatedAt": "2025-03-15T14:30:00Z"
    }
  ],
  "cursor": "eyJpZCI6IjcwMDIifQ"
}

You'll see:

items: Array of project objects
cursor: Pagination token for fetching the next page (null if no more results)

Step 4: Fetch a specific project

Use the project ID from the previous response to fetch full details:

curl https://api.operating.app/v1/projects/7001 \
  -H "Authorization: Bearer $OPERATING_API_KEY"

Expected response:

{
  "id": "7001",
  "name": "Stellar Platform Modernization",
  "clientId": "4001",
  "billingType": "time-and-materials",
  "companyId": "1",
  "siteId": "10",
  "projectOwnerId": "1005",
  "estimatedStartDate": "2025-03-01",
  "estimatedEndDate": "2025-09-30",
  "statusId": "9001",
  "createdAt": "2025-02-01T10:00:00Z",
  "updatedAt": "2025-02-01T10:00:00Z"
}

Single-resource endpoints return the object directly, not wrapped in an items array.

Understanding the response structure

All list endpoints return this structure:

{
  "items": [ /* array of resources */ ],
  "cursor": "pagination_token_or_null"
}

All single-resource endpoints return the object directly.

Common errors

401 Unauthorized

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

Fix: Check that your API key is correct and included in the Authorization header as Bearer YOUR_KEY.

403 Forbidden

{
  "code": "FORBIDDEN",
  "message": "Insufficient permissions to access this resource"
}

Fix: Your API key doesn't have permission to access this resource. Check your API key's permission settings in Operating.

404 Not Found

{
  "code": "NOT_FOUND",
  "message": "Resource not found"
}

Fix: The resource ID doesn't exist, or you don't have permission to see it.

Next steps

API conventions: Pagination, filtering, sorting, and error handling — Learn how to filter lists, paginate through large result sets, and handle errors systematically
How to set up a project with positions, allocations, and rate cards — Create a complete project workflow
How to sync time entries from an external system — Integrate time tracking with your existing tools

Further reading

Authentication reference — Full details on API key management and security
Operating API entity relations — Understand how projects, positions, allocations, and time entries relate to each other
Endpoint reference — Browse all available endpoints at https://operating.readme.io/reference