Services Module
The services module (sso.services) manages applications (services), subscription plans, API keys for service-to-service authentication, AuthOS SAML 2.0 Identity Provider functionality, and billing checkouts.
Core Service Methods
sso.services.create()
Signature:
create(orgSlug: string, payload: CreateServicePayload): Promise<CreateServiceResponse>
Description: Create a new service for an organization. Requires ‘owner’ or ‘admin’ role.
Parameters:
| Name | Type | Description |
|---|---|---|
| orgSlug | string | Organization slug |
| payload | CreateServicePayload | Service creation payload |
Returns: Promise<CreateServiceResponse>
sso.services.list()
Signature:
list(orgSlug: string): Promise<ServiceListResponse>
Description: List all services for an organization.
Returns: Promise<ServiceListResponse>
sso.services.get()
Signature:
get(orgSlug: string, serviceSlug: string): Promise<ServiceResponse>
Description: Get detailed information for a specific service.
Returns: Promise<ServiceResponse>
sso.services.update()
Signature:
update(orgSlug: string, serviceSlug: string, payload: UpdateServicePayload): Promise<Service>
Description: Update service configuration. Requires ‘owner’ or ‘admin’ role.
Returns: Promise<Service>
sso.services.delete()
Signature:
delete(orgSlug: string, serviceSlug: string): Promise<void>
Description: Delete a service and associated data. Requires ‘owner’ role.
Returns: Promise<void>
Plans Module
The plans module (sso.services.plans) manages subscription plans for services.
sso.services.plans.create()
Signature:
plans.create(orgSlug: string, serviceSlug: string, payload: CreatePlanPayload): Promise<PlanResponse>
Description: Create a new subscription plan.
Returns: Promise<PlanResponse>
sso.services.plans.list()
Signature:
plans.list(orgSlug: string, serviceSlug: string): Promise<PlanResponse[]>
Description: List all plans for a service.
Returns: Promise<PlanResponse[]>
sso.services.plans.update()
Signature:
plans.update(orgSlug: string, serviceSlug: string, planId: string, payload: UpdatePlanPayload): Promise<PlanResponse>
Description: Update a subscription plan.
Returns: Promise<PlanResponse>
sso.services.plans.delete()
Signature:
plans.delete(orgSlug: string, serviceSlug: string, planId: string): Promise<void>
Description: Delete a subscription plan. Fails if active subscriptions exist.
Returns: Promise<void>
API Keys Module
The API keys module (sso.services.apiKeys) manages API keys for service-to-service authentication.
sso.services.apiKeys.create()
Signature:
apiKeys.create(orgSlug: string, serviceSlug: string, payload: CreateApiKeyPayload): Promise<ApiKeyCreateResponse>
Description: Create a new API key. The full key is only returned once.
Returns: Promise<ApiKeyCreateResponse>
sso.services.apiKeys.list()
Signature:
apiKeys.list(orgSlug: string, serviceSlug: string, options?: { limit?: number; offset?: number }): Promise<ListApiKeysResponse>
Description: List all API keys for a service.
Returns: Promise<ListApiKeysResponse>
sso.services.apiKeys.get()
Signature:
apiKeys.get(orgSlug: string, serviceSlug: string, apiKeyId: string): Promise<ApiKey>
Description: Get details for a specific API key (full key not returned).
Returns: Promise<ApiKey>
sso.services.apiKeys.delete()
Signature:
apiKeys.delete(orgSlug: string, serviceSlug: string, apiKeyId: string): Promise<void>
Description: Delete an API key immediately.
Returns: Promise<void>
SAML Module
The SAML module (sso.services.saml) configures AuthOS SAML 2.0 Identity Provider functionality.
sso.services.saml.configure()
Signature:
saml.configure(orgSlug: string, serviceSlug: string, payload: ConfigureSamlPayload): Promise<ConfigureSamlResponse>
Description: Configure SAML IdP settings for a service.
Returns: Promise<ConfigureSamlResponse>
sso.services.saml.getConfig()
Signature:
saml.getConfig(orgSlug: string, serviceSlug: string): Promise<SamlConfig>
Description: Get current SAML IdP configuration.
Returns: Promise<SamlConfig>
sso.services.saml.deleteConfig()
Signature:
saml.deleteConfig(orgSlug: string, serviceSlug: string): Promise<ConfigureSamlResponse>
Description: Delete SAML IdP configuration.
Returns: Promise<ConfigureSamlResponse>
sso.services.saml.initiateLogin()
Signature:
saml.initiateLogin(orgSlug: string, serviceSlug: string): Promise<string>
Description: Initiate an IdP-initiated SAML login. Returns an HTML page with an auto-submitting form.
Returns: Promise<string> - HTML content.
Example:
const html = await sso.services.saml.initiateLogin('acme-corp', 'salesforce');
document.body.innerHTML = html; // Auto-submits
sso.services.saml.generateCertificate()
Signature:
saml.generateCertificate(orgSlug: string, serviceSlug: string): Promise<SamlCertificate>
Description: Generate a new SAML signing certificate (deactivates old ones).
Returns: Promise<SamlCertificate>
sso.services.saml.getCertificate()
Signature:
saml.getCertificate(orgSlug: string, serviceSlug: string): Promise<SamlCertificate>
Description: Get the active SAML signing certificate.
Returns: Promise<SamlCertificate>
sso.services.saml.getMetadataUrl()
Signature:
saml.getMetadataUrl(baseURL: string, orgSlug: string, serviceSlug: string): string
Description: Helper to build the SAML IdP metadata URL.
Returns: string
sso.services.saml.getSsoUrl()
Signature:
saml.getSsoUrl(baseURL: string, orgSlug: string, serviceSlug: string): string
Description: Helper to build the SAML SSO endpoint URL.
Returns: string
Billing Module
The billing module (sso.services.billing) manages checkout sessions.
sso.services.billing.createCheckout()
Signature:
billing.createCheckout(orgSlug: string, serviceSlug: string, payload: CreateCheckoutPayload): Promise<CreateCheckoutResponse>
Description: Create a Stripe checkout session for a user to subscribe to a plan. Requires plan to have stripe_price_id configured.
Parameters:
| Name | Type | Description |
|---|---|---|
| orgSlug | string | Organization slug |
| serviceSlug | string | Service slug |
| payload | CreateCheckoutPayload | Checkout payload |
| payload.plan_id | string | Plan ID to subscribe to |
| payload.success_url | string | URL dealing with successful payment |
| payload.cancel_url | string | URL dealing with cancelled payment |
Returns: Promise<CreateCheckoutResponse>
Example:
const checkout = await sso.services.billing.createCheckout('acme-corp', 'main-app', {
plan_id: 'plan_pro',
success_url: 'https://app.acme.com/billing/success?session_id={CHECKOUT_SESSION_ID}',
cancel_url: 'https://app.acme.com/billing/cancel'
});
window.location.href = checkout.checkout_url;
Type Definitions
CreateServicePayload
interface CreateServicePayload {
slug: string;
name: string;
service_type: 'web' | 'mobile' | 'cli' | 'api';
github_scopes?: string[];
google_scopes?: string[];
microsoft_scopes?: string[];
redirect_uris: string[];
}
CreateCheckoutPayload
interface CreateCheckoutPayload {
plan_id: string;
success_url: string;
cancel_url: string;
}
CreateCheckoutResponse
interface CreateCheckoutResponse {
checkout_url: string;
session_id: string;
}
(See Types in SDK for complete definitions)