Organizations API

This guide covers the API endpoints for managing organizations in the Revenue Recognition System. Organizations represent the top-level entity in the system's multi-tenant architecture, providing isolation for customers, subsidiaries, and other financial data.

Organizations are directly linked to Stytch organizations for authentication and access control purposes. All users within a Stytch organization have access to the corresponding organization in the Revenue Recognition System.

Schema

Field	Type	Description	Required
id	UUID	Unique identifier (system-generated)	Read-only
stytchOrgId	String	Corresponding Stytch organization ID	Yes
name	String	Name of the organization	Yes
slug	String	URL-friendly unique identifier	Yes
settings	Object	Organization settings and preferences	No
createdAt	DateTime	When the organization was created	Read-only
updatedAt	DateTime	When the organization was last updated	Read-only

Authentication

Organization API endpoints typically require administrative privileges. The x-stytch-organization-id header is used to identify the organization context, but certain operations may be restricted to system administrators or organization owners.

Endpoints

Create Organization

Create a new organization in the system. This is typically done automatically when a new organization is created in Stytch, but can also be done manually for administrative purposes.

Name
Endpoint
Type
POST /api/v1/organizations
Description
Name
Content-Type
Type
application/json
Description

Request Body

Name
stytchOrgId
Type
string
Required
Description
Stytch organization ID
Name
name
Type
string
Required
Description
Name of the organization
Name
slug
Type
string
Required
Description
URL-friendly unique identifier
Name
settings
Type
object
Description
Organization settings and preferences

Request

curl -X POST https://api.example.com/api/v1/organizations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {admin_token}" \
  -d '{
    "stytchOrgId": "organization-test-6f0cd115-d208-4462-8b0a-d1e8df4568a7",
    "name": "Acme Financial Group",
    "slug": "acme-financial",
    "settings": {
      "fiscalYearStart": "01-01",
      "defaultCurrency": "USD",
      "timezone": "America/Los_Angeles"
    }
  }'

Response

{
  "organization": {
    "id": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
    "stytchOrgId": "organization-test-6f0cd115-d208-4462-8b0a-d1e8df4568a7",
    "name": "Acme Financial Group",
    "slug": "acme-financial",
    "settings": {
      "fiscalYearStart": "01-01",
      "defaultCurrency": "USD",
      "timezone": "America/Los_Angeles"
    },
    "createdAt": "2025-05-11T12:33:59.048Z",
    "updatedAt": "2025-05-11T12:33:59.048Z"
  }
}

List Organizations

Retrieve a list of all organizations. This endpoint is typically restricted to system administrators.

Name
Endpoint
Type
GET /api/v1/organizations
Description

Request

curl -X GET https://api.example.com/api/v1/organizations \
  -H "Authorization: Bearer {admin_token}"

Response

{
  "organizations": [
    {
      "id": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
      "stytchOrgId": "organization-test-6f0cd115-d208-4462-8b0a-d1e8df4568a7",
      "name": "Acme Financial Group",
      "slug": "acme-financial",
      "settings": {
        "fiscalYearStart": "01-01",
        "defaultCurrency": "USD",
        "timezone": "America/Los_Angeles"
      },
      "createdAt": "2025-05-11T12:33:59.048Z",
      "updatedAt": "2025-05-11T12:33:59.048Z"
    },
    {
      "id": "c72e9d34-2b14-4c5a-9fb2-e8a713b42c65",
      "stytchOrgId": "organization-test-7a3bfe25-9c18-4573-9e0a-c2e8df4567b8",
      "name": "Globex Corporation",
      "slug": "globex-corp",
      "settings": {
        "fiscalYearStart": "04-01",
        "defaultCurrency": "EUR",
        "timezone": "Europe/London"
      },
      "createdAt": "2025-05-10T15:22:31.452Z",
      "updatedAt": "2025-05-10T15:22:31.452Z"
    }
  ]
}

Get Organization by ID

Retrieve a specific organization by its internal ID.

Name
Endpoint
Type
GET /api/v1/organizations/{id}
Description

Path Parameters

Name
id
Type
string (UUID)
Required
Description
ID of the organization to retrieve

Request

curl -X GET https://api.example.com/api/v1/organizations/ba3b8cdf-efc1-4a60-88be-ac203d263fe2 \
  -H "x-stytch-organization-id: organization-test-6f0cd115-d208-4462-8b0a-d1e8df4568a7"

Response

{
  "organization": {
    "id": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
    "stytchOrgId": "organization-test-6f0cd115-d208-4462-8b0a-d1e8df4568a7",
    "name": "Acme Financial Group",
    "slug": "acme-financial",
    "settings": {
      "fiscalYearStart": "01-01",
      "defaultCurrency": "USD",
      "timezone": "America/Los_Angeles"
    },
    "createdAt": "2025-05-11T12:33:59.048Z",
    "updatedAt": "2025-05-11T12:33:59.048Z"
  }
}

Lookup Organization by Stytch ID

Lookup and retrieve an organization using the Stytch organization ID.

Name
Endpoint
Type
GET /api/v1/organizations/lookup
Description

Query Parameters

Name
stytchOrgId
Type
string
Required
Description
Stytch organization ID to lookup

Request

curl -X GET "https://api.example.com/api/v1/organizations/lookup?stytchOrgId=organization-test-6f0cd115-d208-4462-8b0a-d1e8df4568a7" \
  -H "x-stytch-organization-id: organization-test-6f0cd115-d208-4462-8b0a-d1e8df4568a7"

Response

{
  "organization": {
    "id": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
    "stytchOrgId": "organization-test-6f0cd115-d208-4462-8b0a-d1e8df4568a7",
    "name": "Acme Financial Group",
    "slug": "acme-financial",
    "settings": {
      "fiscalYearStart": "01-01",
      "defaultCurrency": "USD",
      "timezone": "America/Los_Angeles"
    },
    "createdAt": "2025-05-11T12:33:59.048Z",
    "updatedAt": "2025-05-11T12:33:59.048Z"
  }
}

Update Organization

Update an existing organization's information.

Name
Endpoint
Type
PUT /api/v1/organizations/{id}
Description
Name
Content-Type
Type
application/json
Description

Path Parameters

Name
id
Type
string (UUID)
Required
Description
ID of the organization to update

Request Body

Name
name
Type
string
Description
Name of the organization
Name
slug
Type
string
Description
URL-friendly unique identifier
Name
settings
Type
object
Description
Organization settings and preferences

Request

curl -X PUT https://api.example.com/api/v1/organizations/ba3b8cdf-efc1-4a60-88be-ac203d263fe2 \
  -H "Content-Type: application/json" \
  -H "x-stytch-organization-id: organization-test-6f0cd115-d208-4462-8b0a-d1e8df4568a7" \
  -d '{
    "name": "Acme Global Financial Group",
    "settings": {
      "fiscalYearStart": "01-01",
      "defaultCurrency": "USD",
      "timezone": "UTC"
    }
  }'

Response

{
  "organization": {
    "id": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
    "stytchOrgId": "organization-test-6f0cd115-d208-4462-8b0a-d1e8df4568a7",
    "name": "Acme Global Financial Group",
    "slug": "acme-financial",
    "settings": {
      "fiscalYearStart": "01-01",
      "defaultCurrency": "USD",
      "timezone": "UTC"
    },
    "createdAt": "2025-05-11T12:33:59.048Z",
    "updatedAt": "2025-05-11T14:45:22.183Z"
  }
}

Organization Settings

The settings object can include various configuration preferences for the organization. Common settings include:

Setting	Description	Example Values
fiscalYearStart	Start date of the fiscal year (MM-DD format)	"01-01", "04-01"
defaultCurrency	Default currency for financial transactions	"USD", "EUR", "JPY"
timezone	Default timezone for date/time calculations	"America/New_York"
taxSettings	Tax calculation and reporting preferences	`{...}`
revenueRules	Organization-specific revenue recognition rules	`{...}`

Error Responses

The API returns standard HTTP status codes and error messages in a consistent format.

{
  "message": "Error description",
  "code": "ERROR_CODE",
  "details": { ... }
}

Common errors include:

Status Code	Error Code	Description
400	VALIDATION_ERROR	Request data failed validation
400	DUPLICATE_SLUG	An organization with the provided slug already exists
400	DUPLICATE_ORGANIZATION	An organization with the provided Stytch ID already exists
401	UNAUTHORIZED	User does not have permission to access this organization
404	ORGANIZATION_NOT_FOUND	The requested organization was not found
500	UPDATE_FAILED	Failed to update the organization record

Multi-tenancy and Organization Context

The Revenue Recognition System uses organizations as the primary mechanism for implementing multi-tenancy. Each organization has its own isolated data set including:

Customers
Subsidiaries
Financial data
Configuration settings

When making API requests, the organization context is determined by the x-stytch-organization-id header, which contains the Stytch organization ID. This ID is mapped to an internal organization record to establish the data access boundary.

Finding Your Organization Context

You can find your organization's Stytch ID within the Stytch dashboard or by examining the authentication session information. Once you have the Stytch organization ID, you can use the lookup endpoint to find your organization's internal ID.

Code Example

Here's an example of how to look up an organization by its Stytch ID:

import { apiClient } from '@/lib/db-adapter';

// Look up organization by Stytch ID
async function lookupOrganization(stytchOrgId) {
  try {
    const result = await apiClient.organizations.lookupByStytchId(stytchOrgId);
    
    console.log('Found organization:', result.organization);
    return result.organization;
  } catch (error) {
    console.error('Error looking up organization:', error);
    throw error;
  }
}