API Scoping & Access Control | Ottimate Developer Documentation

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:

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

Access Scoping Levels

API Users can be scoped at three levels:

Scope Level	Access	Use Case
Account-level	All companies and locations within the account	Master integrations managing multiple subsidiaries
Company-level	Single company and all its locations	ERP integration for one legal entity
Location-level	Specific location(s) only	Restricted integration for a single site

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

Common Error: Attempting to create an invoice with an ottimate_location_id that doesn’t belong to the specified ottimate_company_id will result in a validation error.

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).