Skip to main content

​
Overview

The service registration endpoint establishes the initial trust relationship between an AI service and the ATP server. This operation requires administrative authentication and creates persistent credentials for subsequent service operations.

​
Request

Endpoint: POST /api/v1/services
Authentication: Requires Bearer token with administrative privileges

​
Request Body

{
  "name": "Lovelace IDE",
  "description": "AI-powered integrated development environment",
  "callback_url": "https://lovelace.dev/atp/webhook",
  "webhook_secret": "your-secure-random-string"
}
FieldTypeRequiredDescription
namestringYesHuman-readable service identifier
descriptionstringYesService purpose and capabilities description
callback_urlstringYesHTTPS endpoint for receiving user responses
webhook_secretstringYesShared secret for webhook signature verification

​
Response

​
Success Response

Status Code: 201 Created 
{
  "service_id": "lovelace-ide",
  "api_key": "sk_live_lovelace_abc123",
  "webhook_secret": "your-secure-random-string"
}
FieldTypeDescription
service_idstringUnique service identifier for use in subsequent requests
api_keystringAuthentication token for service operations
webhook_secretstringEcho of provided secret for confirmation
The service must securely store the returned api_key and service_id for all future interactions with the ATP server.

​
Error Responses

Status CodeError CodeDescription
400 Bad RequestMISSING_REQUIRED_FIELDRequired field is missing from request
400 Bad RequestINVALID_CALLBACK_URLCallback URL is not a valid HTTPS URL
401 UnauthorizedAUTH_INVALID_TOKENAdmin token is invalid
403 ForbiddenAUTH_INSUFFICIENT_PERMISSIONSToken lacks admin privileges
409 ConflictSERVICE_ALREADY_EXISTSA service with this name already exists

​
Examples

​
cURL Example

curl -X POST "https://atp.example.com/api/v1/services" \
  -H "Authorization: Bearer admin_token_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lovelace IDE",
    "description": "AI-powered integrated development environment",
    "callback_url": "https://lovelace.dev/atp/webhook",
    "webhook_secret": "your-secure-random-string"
  }'

​
Python Example

import requests

admin_token = "admin_token_abc123def456"
service_data = {
    "name": "Lovelace IDE",
    "description": "AI-powered integrated development environment",
    "callback_url": "https://lovelace.dev/atp/webhook",
    "webhook_secret": "your-secure-random-string"
}

response = requests.post(
    "https://atp.example.com/api/v1/services",
    headers={
        "Authorization": f"Bearer {admin_token}",
        "Content-Type": "application/json"
    },
    json=service_data
)

if response.status_code == 201:
    result = response.json()
    # Save these securely
    service_id = result["service_id"]
    api_key = result["api_key"]
    print(f"Service registered with ID: {service_id}")
else:
    print(f"Error: {response.status_code} - {response.json()}")

​
Security Considerations

  • The admin token should be kept highly secure and only used for service registration
  • The webhook_secret should be a high-entropy random string (at least 32 characters)
  • The callback_url must use HTTPS to ensure secure transmission of responses
  • Store the returned api_key securely, treating it as a sensitive credential
⌘I