Organizations API CRUD endpoints for organizations — the top-level scope for projects, policies, and API keys.
Organizations are the top-level grouping in Veto. Every project, policy, tool, and API key belongs to an organization. Each organization has an owner (the user who created it) and a billing tier.
Most endpoints accept both JWT and API key auth. Mutating operations (create, update, delete) require JWT user authentication and cannot be performed with API keys.
List organizations accessible to the authenticated user. API key auth returns only the organization the key belongs to.
Header Required Description X-Veto-API-Key or AuthorizationYes API key or Bearer JWT
{ "data" : [ { "_id" : "org_abc123" , "name" : "Acme Corp" , "slug" : "acme-corp" , "ownerId" : "user_xyz789" , "tier" : "team" , "billingPeriodStart" : "2025-01-01T00:00:00Z" , "createdAt" : "2025-01-15T10:00:00Z" , "updatedAt" : "2025-01-20T14:30:00Z" } ] } curl https://api.veto.so/v1/organizations \ -H "Authorization: Bearer $JWT_TOKEN " Create a new organization. Requires JWT auth (API keys cannot create organizations).
Header Required Description AuthorizationYes Bearer JWT Content-TypeYes application/json
{ "name" : "Acme Corp" , "slug" : "acme-corp" } Field Type Required Description namestringYes Display name (1-100 chars) slugstringYes URL-safe identifier (1-100 chars, lowercase alphanumeric and hyphens only)
{ "_id" : "org_abc123" , "name" : "Acme Corp" , "slug" : "acme-corp" , "ownerId" : "user_xyz789" , "tier" : "free" , "billingPeriodStart" : null , "createdAt" : "2025-01-20T14:30:00Z" , "updatedAt" : null } Status Code Description 403 authorization_errorAPI keys cannot create organizations 409 slug_takenAn organization with this slug already exists
curl -X POST https://api.veto.so/v1/organizations \ -H "Authorization: Bearer $JWT_TOKEN " \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Corp", "slug": "acme-corp" }' Get an organization by ID.
Header Required Description X-Veto-API-Key or AuthorizationYes API key or Bearer JWT
Parameter Type Description idstringOrganization ID
{ "_id" : "org_abc123" , "name" : "Acme Corp" , "slug" : "acme-corp" , "ownerId" : "user_xyz789" , "tier" : "team" , "billingPeriodStart" : "2025-01-01T00:00:00Z" , "createdAt" : "2025-01-15T10:00:00Z" , "updatedAt" : "2025-01-20T14:30:00Z" } Status Code Description 403 authorization_errorNot a member of this organization 404 not_foundOrganization does not exist
curl https://api.veto.so/v1/organizations/org_abc123 \ -H "Authorization: Bearer $JWT_TOKEN " Look up an organization by slug.
Header Required Description X-Veto-API-Key or AuthorizationYes API key or Bearer JWT
Parameter Type Description slugstringOrganization slug
Same shape as GET /v1/organizations/:id.
Status Code Description 403 authorization_errorNot a member of this organization 404 not_foundNo organization with this slug
curl https://api.veto.so/v1/organizations/slug/acme-corp \ -H "Authorization: Bearer $JWT_TOKEN " Update an organization. Requires JWT auth. All body fields are optional (partial update).
Header Required Description AuthorizationYes Bearer JWT Content-TypeYes application/json
Parameter Type Description idstringOrganization ID
{ "name" : "Acme Industries" , "slug" : "acme-industries" } Field Type Required Description namestringNo New display name (1-100 chars) slugstringNo New URL-safe slug (1-100 chars, lowercase alphanumeric and hyphens only)
{ "_id" : "org_abc123" , "name" : "Acme Industries" , "slug" : "acme-industries" , "ownerId" : "user_xyz789" , "tier" : "team" , "billingPeriodStart" : "2025-01-01T00:00:00Z" , "createdAt" : "2025-01-15T10:00:00Z" , "updatedAt" : "2025-01-21T09:00:00Z" } Status Code Description 403 authorization_errorAPI keys cannot update organizations, or not a member 404 not_foundOrganization does not exist 409 slug_takenSlug is already in use by another organization
curl -X PUT https://api.veto.so/v1/organizations/org_abc123 \ -H "Authorization: Bearer $JWT_TOKEN " \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Industries" }' Delete an organization and all associated data. Requires JWT auth. This is irreversible.
Header Required Description AuthorizationYes Bearer JWT
Parameter Type Description idstringOrganization ID
Status Code Description 403 authorization_errorAPI keys cannot delete organizations, or not a member 404 not_foundOrganization does not exist
curl -X DELETE https://api.veto.so/v1/organizations/org_abc123 \ -H "Authorization: Bearer $JWT_TOKEN " Field Type Description _idstringOrganization ID namestringDisplay name slugstringURL-safe identifier ownerIdstringID of the user who owns this org tier"free" | "team" | "business" | "enterprise"Billing tier billingPeriodStartstring?ISO 8601 start of current billing period createdAtstringISO 8601 creation timestamp updatedAtstring?ISO 8601 last update timestamp
