Service Management

Manage the complete lifecycle of external service configurations including creation, retrieval, updates, and deletion.

List All Services

Retrieves a list of all registered external services for your tenant.

Endpoint: GET /api/v1/services

Request

curl -X GET "https://dev.api.authsec.dev/exsvc/api/v1/services" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Items per page (default: 20, max: 100)
`type`	string	No	Filter by service type
`status`	string	No	Filter by status (active, inactive)

Response

Status: 200 OK

{
  "services": [
    {
      "id": "svc_abc123",
      "name": "Payment Gateway",
      "description": "Stripe payment processing",
      "type": "payment",
      "status": "active",
      "base_url": "https://api.stripe.com",
      "api_version": "v1",
      "tenant_id": "tenant_xyz789",
      "created_at": "2026-02-10T10:30:00Z",
      "updated_at": "2026-02-10T10:30:00Z",
      "metadata": {
        "region": "us-east-1"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}

Create a New Service

Endpoint: POST /api/v1/services

Request

curl -X POST "https://dev.api.authsec.dev/exsvc/api/v1/services" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Gateway",
    "description": "Stripe payment processing",
    "type": "payment",
    "base_url": "https://api.stripe.com",
    "api_version": "v1",
    "metadata": {
      "region": "us-east-1",
      "environment": "production"
    }
  }'

Request Body

Field	Type	Required	Description
`name`	string	Yes	Service name (max 255 chars)
`description`	string	No	Service description
`type`	string	Yes	Service type/category
`base_url`	string	Yes	External service base URL
`api_version`	string	No	API version
`status`	string	No	Initial status (default: active)
`metadata`	object	No	Additional service metadata

Response

Status: 201 Created

{
  "id": "svc_abc123",
  "name": "Payment Gateway",
  "description": "Stripe payment processing",
  "type": "payment",
  "status": "active",
  "base_url": "https://api.stripe.com",
  "api_version": "v1",
  "tenant_id": "tenant_xyz789",
  "created_at": "2026-02-11T13:45:00Z",
  "updated_at": "2026-02-11T13:45:00Z",
  "metadata": {
    "region": "us-east-1",
    "environment": "production"
  }
}

Error Responses

409 Conflict - Service with same name already exists:

{
  "error": {
    "code": "SERVICE_EXISTS",
    "message": "A service with name 'Payment Gateway' already exists"
  }
}

Get Service by ID

Retrieve detailed information about a specific service.

Endpoint: GET /api/v1/services/{id}

Request

curl -X GET "https://dev.api.authsec.dev/exsvc/api/v1/services/svc_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Path Parameters

Parameter	Type	Description
`id`	string	Service ID

Response

Status: 200 OK

{
  "id": "svc_abc123",
  "name": "Payment Gateway",
  "description": "Stripe payment processing",
  "type": "payment",
  "status": "active",
  "base_url": "https://api.stripe.com",
  "api_version": "v1",
  "tenant_id": "tenant_xyz789",
  "created_at": "2026-02-10T10:30:00Z",
  "updated_at": "2026-02-10T10:30:00Z",
  "metadata": {
    "region": "us-east-1"
  }
}

Error Responses

404 Not Found - Service doesn't exist:

{
  "error": {
    "code": "SERVICE_NOT_FOUND",
    "message": "Service with ID 'svc_abc123' not found"
  }
}

Update a Service

Update an existing service configuration.

Endpoint: PUT /api/v1/services/{id}

Request

curl -X PUT "https://dev.api.authsec.dev/exsvc/api/v1/services/svc_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe Payment Gateway",
    "description": "Updated payment processing service",
    "status": "active",
    "api_version": "v2",
    "metadata": {
      "region": "us-west-2",
      "environment": "production"
    }
  }'

Path Parameters

Parameter	Type	Description
`id`	string	Service ID

Request Body

All fields are optional. Only include fields you want to update:

Field	Type	Description
`name`	string	Service name
`description`	string	Service description
`type`	string	Service type
`base_url`	string	External service URL
`api_version`	string	API version
`status`	string	Service status
`metadata`	object	Metadata (replaces existing)

Response

Status: 200 OK

{
  "id": "svc_abc123",
  "name": "Stripe Payment Gateway",
  "description": "Updated payment processing service",
  "type": "payment",
  "status": "active",
  "base_url": "https://api.stripe.com",
  "api_version": "v2",
  "tenant_id": "tenant_xyz789",
  "created_at": "2026-02-10T10:30:00Z",
  "updated_at": "2026-02-11T14:00:00Z",
  "metadata": {
    "region": "us-west-2",
    "environment": "production"
  }
}

Delete a Service

Remove a service registration from the system.

Endpoint: DELETE /api/v1/services/{id}

Request

curl -X DELETE "https://dev.api.authsec.dev/exsvc/api/v1/services/svc_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Path Parameters

Parameter	Type	Description
`id`	string	Service ID

Response

Status: 200 OK

{
  "message": "Service deleted successfully",
  "id": "svc_abc123"
}

Error Responses

404 Not Found - Service doesn't exist:

{
  "error": {
    "code": "SERVICE_NOT_FOUND",
    "message": "Service with ID 'svc_abc123' not found"
  }
}

409 Conflict - Service has dependencies:

{
  "error": {
    "code": "SERVICE_IN_USE",
    "message": "Cannot delete service with active integrations",
    "details": {
      "active_credentials": 2
    }
  }
}

Code Examples

Python

import requests

BASE_URL = "https://dev.api.authsec.dev/exsvc"
TOKEN = "your_jwt_token"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# List all services
response = requests.get(f"{BASE_URL}/api/v1/services", headers=headers)
services = response.json()

# Create a new service
new_service = {
    "name": "Email Service",
    "description": "SendGrid email integration",
    "type": "email",
    "base_url": "https://api.sendgrid.com",
    "api_version": "v3"
}
response = requests.post(
    f"{BASE_URL}/api/v1/services",
    json=new_service,
    headers=headers
)
service = response.json()
print(f"Created service: {service['id']}")

# Get service details
service_id = service['id']
response = requests.get(
    f"{BASE_URL}/api/v1/services/{service_id}",
    headers=headers
)
service_details = response.json()

# Update service
updates = {
    "status": "inactive",
    "description": "Deprecated email service"
}
response = requests.put(
    f"{BASE_URL}/api/v1/services/{service_id}",
    json=updates,
    headers=headers
)

# Delete service
response = requests.delete(
    f"{BASE_URL}/api/v1/services/{service_id}",
    headers=headers
)
print("Service deleted")

TypeScript

const BASE_URL = "https://dev.api.authsec.dev/exsvc";
const TOKEN = "your_jwt_token";

const headers = {
  "Authorization": `Bearer ${TOKEN}`,
  "Content-Type": "application/json"
};

// List all services
async function listServices() {
  const response = await fetch(`${BASE_URL}/api/v1/services`, {
    headers
  });
  const data = await response.json();
  return data.services;
}

// Create a new service
async function createService() {
  const newService = {
    name: "Email Service",
    description: "SendGrid email integration",
    type: "email",
    base_url: "https://api.sendgrid.com",
    api_version: "v3"
  };
  
  const response = await fetch(`${BASE_URL}/api/v1/services`, {
    method: "POST",
    headers,
    body: JSON.stringify(newService)
  });
  
  const service = await response.json();
  console.log(`Created service: ${service.id}`);
  return service;
}

// Get service by ID
async function getService(serviceId: string) {
  const response = await fetch(
    `${BASE_URL}/api/v1/services/${serviceId}`,
    { headers }
  );
  return await response.json();
}

// Update service
async function updateService(serviceId: string) {
  const updates = {
    status: "inactive",
    description: "Deprecated email service"
  };
  
  const response = await fetch(
    `${BASE_URL}/api/v1/services/${serviceId}`,
    {
      method: "PUT",
      headers,
      body: JSON.stringify(updates)
    }
  );
  return await response.json();
}

// Delete service
async function deleteService(serviceId: string) {
  const response = await fetch(
    `${BASE_URL}/api/v1/services/${serviceId}`,
    {
      method: "DELETE",
      headers
    }
  );
  return await response.json();
}

Best Practices

1. Service Naming

Use descriptive, unique names
Follow consistent naming conventions
Include environment in name if managing multiple (e.g., "Stripe Production", "Stripe Staging")

2. Metadata Usage

Store environment-specific configuration in metadata
Use metadata for feature flags and settings
Keep metadata JSON serializable

3. Service Types

Use consistent type categorization (payment, email, storage, etc.)
Leverage types for filtering and organization
Document your type taxonomy

4. Status Management

Set services to inactive before deletion
Monitor inactive services for cleanup
Implement soft-delete patterns when needed

5. Error Handling

Always check response status codes
Implement retry logic for transient errors
Log errors for debugging

Next Steps

Credential Management - Securely store and retrieve service credentials
Debug Utilities - Troubleshoot authentication issues
API Conventions - Common patterns and best practices

List All Services​

Request​

Query Parameters​

Response​

Create a New Service​

Request​

Request Body​

Response​

Error Responses​

Get Service by ID​

Request​

Path Parameters​

Response​

Error Responses​

Update a Service​

Request​

Path Parameters​

Request Body​

Response​

Delete a Service​

Request​

Path Parameters​

Response​

Error Responses​

Code Examples​

Python​

TypeScript​

Best Practices​

1. Service Naming​

2. Metadata Usage​

3. Service Types​

4. Status Management​

5. Error Handling​

Next Steps​

List All Services

Request

Query Parameters

Response

Create a New Service

Request

Request Body

Response

Error Responses

Get Service by ID

Request

Path Parameters

Response

Error Responses

Update a Service

Request

Path Parameters

Request Body

Response

Delete a Service

Request

Path Parameters

Response

Error Responses

Code Examples

Python

TypeScript

Best Practices

1. Service Naming

2. Metadata Usage

3. Service Types

4. Status Management

5. Error Handling

Next Steps