External Services Overview

The External Service API enables you to manage external service integrations, store and retrieve credentials securely, and debug authentication flows across your multi-tenant environment.

Base URL

https://dev.api.authsec.dev/exsvc

Live Documentation: Swagger UI

---

Key Features

• Service Registry: Centralized management of external service configurations
• Credential Management: Secure storage and retrieval of service credentials
• Lifecycle Management: Complete CRUD operations for service definitions
• Debug Utilities: Authentication claim inspection and troubleshooting
• Multi-Tenant Support: Service isolation across tenant boundaries
• Bearer Authentication: JWT-based secure access control

---

Authentication

All endpoints require Bearer token authentication. Include your JWT token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Token Requirements:

• Valid JWT issued by Auth Manager
• Appropriate permissions/scopes for service management
• Active, non-expired token

---

Service Object

A service object represents an external service integration with the following properties:

Property	Type	Description
id	string	Unique service identifier
name	string	Service name
description	string	Service description
type	string	Service type/category
status	string	Service status (active, inactive)
base_url	string	External service base URL
api_version	string	API version
tenant_id	string	Associated tenant identifier
created_at	timestamp	Creation timestamp
updated_at	timestamp	Last update timestamp
metadata	object	Additional service metadata

---

API Sections

Service Management

Complete CRUD operations for managing external service configurations.

Endpoints:

• List all services
• Create new service
• Get service by ID
• Update service
• Delete service

Documentation: Services

---

Credential Management

Secure storage and retrieval of service authentication credentials.

Endpoints:

• Get service credentials

Documentation: Credentials

---

Debug Utilities

Tools for troubleshooting authentication and verifying security context.

Endpoints:

• Debug authentication claims

Documentation: Debug

---

Common Use Cases

1. Register a New External Service

POST /api/v1/services
{
  "name": "Payment Gateway",
  "description": "Stripe payment processing",
  "type": "payment",
  "base_url": "https://api.stripe.com",
  "api_version": "v1"
}

2. Retrieve Service Credentials

GET /api/v1/services/{service-id}/credentials

3. Debug Authentication Token

GET /debug/auth
Authorization: Bearer YOUR_TOKEN

Returns the parsed claims from your JWT to verify permissions.

---

Security Considerations

Best Practices

1. Credential Storage:

   • Never log or expose credentials in client code
   • Use environment variables for sensitive data
   • Rotate credentials regularly

2. Token Management:

   • Store JWT tokens securely
   • Implement token refresh logic
   • Handle token expiration gracefully

3. Service Configuration:

   • Use HTTPS for all external service URLs
   • Validate service responses
   • Implement timeout and retry logic

4. Access Control:

   • Grant minimum required permissions
   • Audit service access regularly
   • Implement role-based access for service management

---

Error Handling

The API uses standard HTTP status codes:

Status Code	Meaning
200 OK	Request successful
201 Created	Service created successfully
400 Bad Request	Invalid request payload
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	Insufficient permissions
404 Not Found	Service not found
409 Conflict	Service already exists
500 Internal Server Error	Server error

Error Response Format:

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

---

Rate Limiting

The External Service API implements rate limiting to ensure fair usage:

• Rate Limit: 100 requests per minute per tenant
• Headers:
  • X-RateLimit-Limit: Total requests allowed
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Time when limit resets (Unix timestamp)

Exceeded Limit Response:

429 Too Many Requests
Retry-After: 60

---

Getting Started

1. Obtain Authentication Token: Use the Auth Manager to generate a JWT
2. Register a Service: Create your first external service configuration
3. Store Credentials: Save service authentication credentials securely
4. Retrieve and Use: Fetch credentials when needed for external API calls

---

Next Steps

• Service Management - CRUD operations for services
• Credential Management - Secure credential handling
• Debug Utilities - Troubleshooting tools
• API Conventions - Common patterns and best practices

---

Version: 1.0
Last Updated: 2026-02-11