Management API - Application Creation Flow

Overview

The Management API provides endpoints for creating and managing applications (OAuth2 clients) in the Champion platform. Applications can be either token-exchange or service-account type, integrated with Auth0 for authentication.

API Endpoint

Create Application

POST /management/accounts/{accountUUID}/applications

Required Scopes: create:applications

Request Body

{
  "type": "token-exchange | service-account",
  "organizationId": "string",
  "organizationName": "string",
  "productId": "string",
  "name": "string",
  "description": "string (optional)"
}

Response (201 Created)

{
  "uuid": "uuid",
  "auth0ClientId": "string",
  "accountUUID": "uuid",
  "organizationId": "string",
  "productId": "string",
  "applicationType": "token-exchange | service-account",
  "name": "string",
  "description": "string",
  "createdBy": "uuid",
  "createdAt": "datetime",
  "updatedAt": "datetime",
  "clientSecret": "string (one-time only)"
}

Complete Flow

1. Authentication & Authorization

Request must include valid OAuth2 token with create:applications scope
Token can be from:
- User with appropriate role in the account
- Product service account (can only create apps for their consumer/product)

2. Request Validation (Handler Layer)

File: internal/champion/handler/management/applications.go

Extract token data to identify requester
For product service accounts: Verify productId matches token's consumer
Extract user UUID for audit trail (nil for service accounts)
Prepare parameters for service layer

3. Business Logic (Service Layer)

File: internal/champion/service/application_service.go

3.1 Name Uniqueness Check

Verify application name is unique within the account
Query: CheckApplicationNameExists
Returns error if name already exists

3.2 Transaction Execution

All following steps execute within a database transaction:

3.3 Auth0 Application Creation

Create Auth0 non-interactive application
Name format: {productId}-{sanitized-org-name}-{type}
- Organization name sanitization:
  - Convert to lowercase
  - Replace spaces/special chars with hyphens
  - Remove consecutive hyphens
  - Truncate to fit 80-char limit
Set client metadata:

{
  "type": "champion-{type}",
  "owner": "champion-server",
  "created_by": "uuid",
  "account_uuid": "uuid",
  "organization_id": "string",
  "client_name": "productId"
}

Capture generated client secret

3.4 Grant Scopes

Based on application type:

Token-Exchange Applications:

write:linked-accounts
read:linked-accounts
read:chats
write:chats
create:chats
read:tool-management
read:tool-auth
read:user-context
update:user-context
delete:user-context

Service-Account Applications:

Basic access to resource server (no specific scopes currently)

3.5 Database Storage

Table: application Query: CreateApplication

Fields stored:

auth0_client_id: From Auth0 response
account_uuid: Account owning the application
organization_id: Organization identifier
product_id: Product/consumer identifier
application_type: token-exchange or service-account
name: User-provided name
description: Optional description
created_by: User UUID or NULL for service accounts

3.6 Audit Trail Creation

Table: application_audit

Creates audit record with:

action: "create"
changed_by: User UUID
changes: JSON with all application fields
changed_at: Current timestamp

4. Response

Returns created application with:

All stored fields
One-time client secret (not stored in database)
Generated UUID
Timestamps

Example Curl Commands

curl -X POST "https://api.champion.ai/champion/api/management/accounts/{ACCOUNT_UUID}/applications" \
  -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "token-exchange",
    "organizationId": "org-12345",
    "organizationName": "Acme Manufacturing",
    "productId": "redzone",
    "name": "Acme Token Exchange App",
    "description": "Token exchange application for Acme Manufacturing RedZone integration"
  }'

Replace:

{ACCOUNT_UUID} - Your account's UUID
{YOUR_ACCESS_TOKEN} - Valid OAuth2 token with create:applications scope

Example with actual values:

curl -X POST "https://api.champion.ai/champion/api/management/accounts/{ACCOUNT_UUID}/applications" \
  -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "token-exchange",
    "organizationId": "factory-west",
    "organizationName": "West Coast Factory",
    "productId": "dscp",
    "name": "DSCP Integration Client",
    "description": "OAuth2 client for DSCP token exchange"
  }'

Successful Response (201):

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "auth0ClientId": "xYz123AbC456...",
  "accountUUID": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "factory-west",
  "productId": "dscp",
  "applicationType": "token-exchange",
  "name": "DSCP Integration Client",
  "description": "OAuth2 client for DSCP token exchange",
  "createdBy": "987e6543-e21b-12d3-a456-426614174000",
  "createdAt": "2024-01-30T12:00:00Z",
  "updatedAt": "2024-01-30T12:00:00Z",
  "clientSecret": "super-secret-value-only-shown-once"
}

Error Handling

400 Bad Request

Invalid request body format
Missing required fields

401 Unauthorized

Missing or invalid authentication token

403 Forbidden

Insufficient permissions
Product service account trying to create app for different consumer

409 Conflict

Application name already exists in account

500 Internal Server Error

Auth0 API failure
Database connection issues
Transaction rollback

Security Considerations

Client Secret: Only returned once during creation, never stored or retrievable
Scope Isolation: Different application types get different scopes
Consumer Isolation: Product service accounts can only create apps for their consumer
Audit Trail: All operations are logged with user/system attribution
Transaction Safety: All operations rolled back on any failure

Related Operations

List Applications: GET /management/accounts/{accountUUID}/applications
Get Application: GET /management/accounts/{accountUUID}/applications/{applicationUUID}
Update Application: PATCH /management/accounts/{accountUUID}/applications/{applicationUUID}
Delete Application: DELETE /management/accounts/{accountUUID}/applications/{applicationUUID}
Get Audit Trail: GET /management/accounts/{accountUUID}/applications/{applicationUUID}/audit