Service Management API on AuthOS Docs | Auth Operating System API and SDK Guides

Service Endpoint Reference

Mon, 01 Jan 0001 00:00:00 +0000

Data Models

Service Model

{
  "id": "uuid",
  "org_id": "uuid",
  "slug": "unique-service-identifier",
  "name": "Service Name",
  "service_type": "web|mobile|desktop|api",
  "client_id": "uuid",
  "github_scopes": ["user:email", "read:user"],
  "microsoft_scopes": ["openid", "profile", "email"],
  "google_scopes": ["openid", "email", "profile"],
  "redirect_uris": ["https://app.example.com/callback"],
  "device_activation_uri": "https://app.example.com/device",
  "created_at": "datetime"
}

Plan Model

{
  "id": "uuid",
  "service_id": "uuid",
  "name": "Plan Name",
  "description": "Optional plan description",
  "price_cents": 1999,
  "currency": "usd",
  "features": ["feature1", "feature2"],
  "stripe_price_id": "price_1234567890 (optional)",
  "is_default": false,
  "created_at": "datetime"
}

Service with Details

{
  "id": "uuid",
  "org_id": "uuid",
  "slug": "main-app",
  "name": "Main Application",
  "service_type": "web",
  "client_id": "550e8400-e29b-41d4-a716-446655440000",
  "github_scopes": ["user:email"],
  "microsoft_scopes": ["openid", "email"],
  "google_scopes": ["openid", "email"],
  "redirect_uris": ["https://app.example.com/callback"],
  "device_activation_uri": null,
  "created_at": "2025-01-15T10:30:00Z",
  "plan_count": 3,
  "subscription_count": 150
}

Endpoints Summary

Method	Path	Description	Permissions
POST	`/api/organizations/:org_slug/services`	Create new service	Owner/Admin
GET	`/api/organizations/:org_slug/services`	List organization services	Member
GET	`/api/organizations/:org_slug/services/:service_slug`	Get service details	Member
PATCH	`/api/organizations/:org_slug/services/:service_slug`	Update service	Owner/Admin
DELETE	`/api/organizations/:org_slug/services/:service_slug`	Delete service	Owner
POST	`/api/organizations/:org_slug/services/:service_slug/plans`	Create plan	Owner/Admin
GET	`/api/organizations/:org_slug/services/:service_slug/plans`	List service plans	Member
PATCH	`/api/organizations/:org_slug/services/:service_slug/plans/:plan_id`	Update plan	Owner/Admin
DELETE	`/api/organizations/:org_slug/services/:service_slug/plans/:plan_id`	Delete plan	Owner/Admin
POST	`/api/organizations/:org_slug/services/:service_slug/checkout`	Create Stripe checkout session	Member

Service Operations

POST /api/organizations/:org_slug/services

Create a new service with automatic plan provisioning.

Plan and Checkout Reference

Mon, 01 Jan 0001 00:00:00 +0000

Plan Management

POST /api/organizations/:org_slug/services/:service_slug/plans

Create a new subscription plan for a service.

Permissions: Owner or Admin

Headers:

Header	Value
`Authorization`	`Bearer {jwt}`

Path Parameters:

Parameter	Type	Description
`org_slug`	string	Organization slug
`service_slug`	string	Service slug

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Plan name (e.g., “Pro”, “Enterprise”)
`description`	string	No	Optional plan description
`price_cents`	integer	Yes	Price in cents (e.g., 1999 for $19.99)
`currency`	string	Yes	Currency code (e.g., “usd”, “eur”)
`features`	string[]	No	List of features included in the plan
`stripe_price_id`	string	No	Optional Stripe price ID for billing
`is_default`	boolean	No	Whether this is the default plan for the service (default: false)

Example Request:

Service Billing Integration Recipes

Mon, 01 Jan 0001 00:00:00 +0000

Stripe Integration

Services can be monetized using Stripe. To enable billing:

Configure STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET env vars
Create Products and Prices in Stripe Dashboard
Associate Stripe Price IDs when creating Plans
Use the Checkout endpoint to subscribe users

Organizations have service limits based on their tier. When a service is created, a default “Free” plan is automatically provisioned.

Provision a purchasable plan

Create the Stripe Product and Price in the Stripe Dashboard.
Create the AuthOS plan with that Price’s stripe_price_id.
Present the returned plan ID in your application’s plan picker.
Submit that plan ID with trusted success and cancel URLs to the checkout endpoint.
Confirm subscription state after Stripe redirects the browser.

Use the plan and checkout reference for request fields and response contracts. Do not treat the browser redirect alone as proof that a subscription was recorded.

Service Security and Operations

Mon, 01 Jan 0001 00:00:00 +0000

Security Considerations

Service Limits:

Organizations have service limits based on their tier
Free tier typically allows 5 services
Limits can be customized per organization by Platform Owners
Service creation fails if limit is reached

Access Control:

Only owners and admins can create/modify services and plans
Only owners can delete services
All members can view services and plans
Organization must be active for service operations

Validation:

Service type must be one of: web, mobile, desktop, api
Service slug must be unique within the organization
Plan price must be non-negative
Currency should be valid ISO 4217 code

OAuth Configuration:

Service Management Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Start with the HTTP status and structured error response, then verify the organization, service, plan, caller role, and external billing configuration.

Symptom guide

Symptom	Check	Resolution
Service creation returns 400	Organization service limit, slug uniqueness, and service type	Remove an unused service, request a limit change, choose a unique slug, or use a supported type
Management returns 401	Bearer token and Authorization header	Obtain a current organization-management JWT
Update or plan mutation returns 403	Caller membership and owner/admin role	Use a caller with the required organization role
Service or plan returns 404	Organization slug, service slug, and plan ID	Load the parent resource first and use its canonical identifiers
Service deletion returns 400	Active subscriptions	Cancel or migrate subscriptions before deletion
Plan deletion returns 400	Active subscriptions on the plan	Migrate subscribers and confirm the active count is zero
OAuth callback fails after an update	Exact redirect URI and provider scopes	Register the production HTTPS callback and retest the provider flow
Checkout reports a missing price	Plan’s `stripe_price_id`	Associate the correct test or live Stripe Price with the plan
Checkout returns 500	Stripe credentials, webhook configuration, and environment mode	Verify server-side Stripe configuration without exposing secrets
Counts appear stale	Selected service and completed subscription lifecycle	Reload service details after the relevant asynchronous billing work completes

Safe diagnostic sequence

Reproduce with the smallest management request.
Record the status, error_code, and timestamp without recording credentials.
Confirm the organization is active and the caller has the documented role.
Inspect the service or plan with a GET request before retrying a mutation.
For checkout failures, compare AuthOS and Stripe environments and identifiers.
Use API error handling for retry and logging patterns.