Service API Module
The Service API module (sso.serviceApi) provides backend service-to-service communication. All methods require API key authentication via the X-Api-Key header and are scoped to the service associated with the API key.
Authentication Setup
To use the Service API, you must first create an API key through the SDK:
// Create an API key (as an admin)
const apiKey = await sso.services.apiKeys.create('acme-corp', 'main-app', {
name: 'Production Backend',
permissions: ['read:users', 'write:users', 'write:subscriptions'],
expires_in_days: 90
});
// IMPORTANT: Store this key securely - it's only shown once!
console.log('API Key:', apiKey.key);
Then initialize the SDK with the API key:
import { SsoClient } from '@drmhse/sso-sdk';
const sso = new SsoClient({
baseURL: 'https://sso.example.com',
apiKey: 'sk_live_abcd1234...' // Your API key
});
// Now you can use sso.serviceApi methods
const user = await sso.serviceApi.createUser({ email: 'user@example.com' });
User Management
sso.serviceApi.listUsers()
Signature:
listUsers(params?: { limit?: number; offset?: number }): Promise<ListUsersResponse>
Description: List all users for the service.
Required Permission: read:users
Returns: Promise<ListUsersResponse>
sso.serviceApi.getUser()
Signature:
getUser(userId: string): Promise<ServiceApiUser>
Description: Get a specific user by ID.
Required Permission: read:users
Returns: Promise<ServiceApiUser>
sso.serviceApi.createUser()
Signature:
createUser(request: CreateUserRequest): Promise<ServiceApiUser>
Description: Create a new user in AuthOS for your service.
Required Permission: write:users
Returns: Promise<ServiceApiUser>
sso.serviceApi.updateUser()
Signature:
updateUser(userId: string, request: UpdateUserRequest): Promise<ServiceApiUser>
Description: Update user details such as email address.
Required Permission: write:users
Returns: Promise<ServiceApiUser>
sso.serviceApi.deleteUser()
Signature:
deleteUser(userId: string): Promise<void>
Description: Permanently delete a user from your service.
Required Permission: delete:users
Returns: Promise<void>
Subscription Management
sso.serviceApi.listSubscriptions()
Signature:
listSubscriptions(params?: { limit?: number; offset?: number }): Promise<ListSubscriptionsResponse>
Description: List all subscriptions for the service.
Required Permission: read:subscriptions
Returns: Promise<ListSubscriptionsResponse>
sso.serviceApi.getSubscription()
Signature:
getSubscription(userId: string): Promise<ServiceApiSubscription>
Description: Get subscription for a specific user.
Required Permission: read:subscriptions
Returns: Promise<ServiceApiSubscription>
sso.serviceApi.createSubscription()
Signature:
createSubscription(request: CreateSubscriptionRequest): Promise<ServiceApiSubscription>
Description: Create a new subscription for a user.
Required Permission: write:subscriptions
Returns: Promise<ServiceApiSubscription>
sso.serviceApi.updateSubscription()
Signature:
updateSubscription(userId: string, request: UpdateSubscriptionRequest): Promise<ServiceApiSubscription>
Description: Update a user’s subscription status or renewal date.
Required Permission: write:subscriptions
Returns: Promise<ServiceApiSubscription>
sso.serviceApi.deleteSubscription()
Signature:
deleteSubscription(userId: string): Promise<void>
Description: Permanently delete a user’s subscription.
Required Permission: delete:subscriptions
Returns: Promise<void>
Analytics
sso.serviceApi.getAnalytics()
Signature:
getAnalytics(): Promise<ServiceAnalytics>
Description: Get analytics for the service.
Required Permission: read:analytics
Returns: Promise<ServiceAnalytics>
Service Configuration
sso.serviceApi.getServiceInfo()
Signature:
getServiceInfo(): Promise<ServiceApiInfo>
Description: Get service information.
Required Permission: read:service
Returns: Promise<ServiceApiInfo>
sso.serviceApi.updateServiceInfo()
Signature:
updateServiceInfo(request: UpdateServiceInfoRequest): Promise<ServiceApiInfo>
Description: Update service configuration details.
Required Permission: write:service
Returns: Promise<ServiceApiInfo>
Type Definitions
(Refer to SDK type definitions for full definitions)