OpenAPI Specification
openapi: 3.1.0
info:
title: UrbanFox Customer Cases Snippet API
version: 2.0.0
summary: Fraud case management, end-user accounts, and tenant operations for UrbanFox customers.
description: 'REST API for UrbanFox tenants to manage fraud cases, end-user accounts, tenant
metrics, and machine-to-machine credentials.
## Authentication
JWT Bearer tokens, issued by `POST /v2/oauth/token` via the OAuth 2.0 client-credentials flow.
## Authorization
Each protected operation declares its required scope in its OAuth 2.0 security requirement.
Tokens missing the required scope receive a `403`.
## Versioning
Versioned via the URL path (`/v2/...`).
'
contact:
name: UrbanFox
license:
name: Proprietary - UrbanFox
servers:
- url: https://api.{tenant_slug}.urbanfox.io
description: 'Per-tenant API host. The {tenant_slug} subdomain matches the {tenant_slug} path parameter on each operation. Example: a tenant with slug ''demo-retail'' calls https://api.demo-retail.urbanfox.io/v2/demo-retail/cases.'
variables:
tenant_slug:
default: demo-retail
description: Tenant DNS slug (lowercase, hyphenated).
security:
- oauth2: []
tags:
- name: Snippet
description: Tenant integration snippet retrieval.
paths:
/v2/{tenant_slug}/snippet:
get:
summary: Get integration snippets
description: Retrieve integration snippets and identifiers for a tenant.
operationId: getSnippet
parameters:
- description: Tenant DNS slug (lowercase letters, digits, and hyphens; 3-100 characters).
required: true
schema:
type: string
maxLength: 100
minLength: 3
pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
title: Tenant Name
description: Tenant DNS slug (lowercase letters, digits, and hyphens; 3-100 characters).
examples:
- demo-retail
name: tenant_slug
in: path
responses:
'422':
description: Request Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetail'
example:
type: validation-error
title: Request Validation Failed
status: 422
detail: One or more fields failed validation
errors:
- field: path.tenant_slug
message: Validation failed
type: validation_error
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/APIResponse_SnippetResponse_'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetail'
example:
type: bad-request
title: Bad Request
status: 400
detail: Malformed request
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetail'
example:
type: unauthorized
title: Unauthorized
status: 401
detail: Authentication required
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetail'
example:
type: internal-error
title: Internal Server Error
status: 500
detail: Internal server error
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetail'
example:
type: item-not-found
title: Application Error
status: 404
detail: 'Tenant not found with name: demo-retail'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetail'
example:
type: forbidden
title: Forbidden
status: 403
detail: Access denied
tags:
- Snippet
security:
- oauth2:
- read:snippet
components:
schemas:
SnippetItem:
properties:
framework:
type: string
enum:
- HTML
- PlaceHolder
title: Framework
description: Target platform for the snippet. `HTML` is the browser script tag; `PlaceHolder` is reserved for future native SDK targets.
examples:
- HTML
readOnly: true
snippet:
type: string
minLength: 1
title: Snippet
description: Drop-in integration snippet pre-configured with the tenant's `app_id` and collector endpoint
examples:
- "<script src=\"https://cdn.example.com/clickstream-web.min.js\"></script>\n<script>\n window.ClickstreamAnalytics.init({\n appId: \"demo-retail_00000000000000000000000000000001\",\n endpoint: \"https://collector.example.com\",\n globalAttributes: {\n tenant_id: \"00000000-0000-4000-8000-000000000000\"\n }\n })\n</script>"
readOnly: true
additionalProperties: false
type: object
required:
- framework
- snippet
title: SnippetItem
APIResponse_SnippetResponse_:
properties:
data:
$ref: '#/components/schemas/SnippetResponse'
description: Response payload
readOnly: true
type: object
required:
- data
title: APIResponse[SnippetResponse]
ProblemDetail:
properties:
type:
type: string
title: Type
description: URI reference (or identifier) for problem type
default: about:blank
examples:
- validation-error
readOnly: true
title:
type: string
title: Title
description: Short, human-readable summary
examples:
- Validation Failed
readOnly: true
status:
type: integer
maximum: 599.0
minimum: 100.0
title: Status
description: HTTP status code
examples:
- 400
readOnly: true
detail:
anyOf:
- type: string
- type: 'null'
title: Detail
description: Human-readable explanation (MUST NOT contain PII or sensitive data)
examples:
- Request validation failed on one or more fields
readOnly: true
instance:
anyOf:
- type: string
- type: 'null'
title: Instance
description: URI reference identifying this specific occurrence (e.g., request ID)
examples:
- /v2/demo-retail/cases/case-abc123
readOnly: true
errors:
anyOf:
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Errors
description: Validation errors (extension member)
examples:
- - field: status
message: Input should be 'OPEN' or 'CLOSED'
type: enum
readOnly: true
type: object
required:
- title
- status
title: ProblemDetail
SnippetResponse:
properties:
snippets:
items:
$ref: '#/components/schemas/SnippetItem'
type: array
minItems: 1
title: Snippets
description: Integration snippets, one per supported target platform
examples:
- - framework: HTML
snippet: "<script src=\"https://cdn.example.com/clickstream-web.min.js\"></script>\n<script>\n window.ClickstreamAnalytics.init({\n appId: \"demo-retail_00000000000000000000000000000001\",\n endpoint: \"https://collector.example.com\",\n globalAttributes: {\n tenant_id: \"00000000-0000-4000-8000-000000000000\"\n }\n })\n</script>"
readOnly: true
tenant_name:
type: string
minLength: 1
title: Tenant Name
description: Tenant slug returned as tenant_name for compatibility
examples:
- demo-retail
readOnly: true
app_id:
type: string
minLength: 1
title: App Id
description: 'Clickstream application identifier embedded in the snippet (format: `<tenant_slug>_<32-char-hex>`)'
examples:
- demo-retail_00000000000000000000000000000001
readOnly: true
tenant_id:
type: string
minLength: 1
format: uuid
title: Tenant Id
description: Tenant identifier sent as `globalAttributes.tenant_id` on every clickstream event
examples:
- 00000000-0000-4000-8000-000000000000
readOnly: true
additionalProperties: false
type: object
required:
- snippets
- tenant_name
- app_id
- tenant_id
title: SnippetResponse
securitySchemes:
oauth2:
type: oauth2
description: 'OAuth 2.0 client-credentials flow. Request a token from `POST /v2/oauth/token` and send it as `Authorization: Bearer <access_token>`.'
flows:
clientCredentials:
tokenUrl: https://api.demo-retail.urbanfox.io/v2/oauth/token
scopes:
create:enduseraccount: Create an end-user account
delete:enduseraccount: Delete an end-user account
read:case: Get a case
read:cases: List cases
read:enduseraccount: Get an end-user account
read:enduseraccounts: List end-user accounts
read:metrics: Get tenant metrics
read:snippet: Get integration snippets
read:tenant: Get tenant
read:tenant_auth_secret: Get tenant OAuth client credentials
update:case: Update a case
update:enduseraccount: Update an end-user account
update:tenant_auth_secret: Rotate tenant OAuth client secret