API Scoping & Access Control

Data Access and API Scoping

All API integrations in Ottimate operate through OAuth applications tied to a specific API User. Understanding how data access is scoped is critical for integrations, especially in multi-company accounts.

OAuth Apps and API Users

When you integrate with Ottimate:

1. OAuth App - Your integration application authenticates using Client ID and Client Secret
2. API User - Every OAuth app operates on behalf of an API User provisioned by Ottimate
3. Access Scope - The API User determines what data your integration can access

Access Scoping Levels

API Users can be scoped at three levels:

Examples:

Account-Scoped API User:

1
// Can access data across all companies
2
GET /v1/invoices?ottimate_company_id=123  // ✅ Allowed
3
GET /v1/invoices?ottimate_company_id=789  // ✅ Allowed
4
GET /v1/vendors?ottimate_company_id=123   // ✅ Allowed

Company-Scoped API User (Company 123 only):

1
// Can only access Company 123 data
2
GET /v1/invoices?ottimate_company_id=123  // ✅ Allowed
3
GET /v1/invoices?ottimate_company_id=789  // ❌ Forbidden
4
GET /v1/vendors?ottimate_company_id=123   // ✅ Allowed

Location-Scoped API User (Location 456 only):

1
// Can only access Location 456 data
2
GET /v1/invoices?ottimate_location_id=456  // ✅ Allowed
3
GET /v1/invoices?ottimate_location_id=457  // ❌ Forbidden

Resource Scoping in API Calls

Every API request that creates or retrieves data must specify the appropriate company and/or location scope.

Company Scoping

Most API endpoints require ottimate_company_id to specify which company’s data you’re working with.

Examples:

$
# List all vendors for a specific company
$
GET /v1/vendors?ottimate_company_id=123
$
$
# Create a dimension for a specific company
$
POST /v1/dimensions
$
{
>
  "ottimate_company_id": 123,
>
  "type": "account",
>
  "name": "Office Supplies",
>
  "erp_dimension_id": "5010"
>
}
$
$
# List invoices for a specific company
$
GET /v1/invoices?ottimate_company_id=123

Location Scoping

Invoices must be assigned to a specific location. Other resources (vendors, dimensions) are company-level and shared across all locations.

Examples:

$
# Create an invoice for a specific location
$
POST /v1/invoices
$
{
>
  "ottimate_company_id": 123,
>
  "ottimate_location_id": 456,
>
  "ottimate_vendor_id": 789,
>
  "invoice_number": "INV-001",
>
  "total_amount": 1000.00
>
}
$
$
# Filter invoices by location
$
GET /v1/invoices?ottimate_company_id=123&ottimate_location_id=456

Finding the Right IDs

To determine which company and location IDs to use:

Step 1: List all companies

$
GET /v1/accounts/{account_id}/companies

Step 2: List all locations

$
GET /v1/accounts/{account_id}/locations

Step 3: Match to your business logic

When creating an invoice, determine which company and location it belongs to based on your business rules (e.g., which ERP it came from, which site received the goods).