The AMFG Public API provides a secure, streamlined REST interface for managing custom integrations, retrieving resource lists, and synchronizing order, part, and logistics data with external systems.
This guide outlines the core authentication requirements, failure behaviors, and operational API conventions necessary to integrate effectively with the AMFG ecosystem.
Authentication
All requests to the AMFG Public API require authentication via a single HTTP header containing an Incoming Secret.
Key Generation and Credentials
Incoming Secrets can be generated in one of two ways:
Console: Navigate to Settings -> API Keys in the Management Console.
API Endpoint: Issue a
POST /api/v1/secretrequest.
The secret value is formatted as:
<secretId>.<random>
Important Security Notice: The secret string is displayed only once upon creation. Store it securely in your secret manager or environment configuration. If lost, the secret cannot be retrieved and must be regenerated.
Header Configuration
Pass the secret in the HTTP Authorization header on every request. A Bearer prefix is accepted but optional:
HTTP
Authorization: <secret>
or
HTTP
Authorization: Bearer <secret>
Legacy Key Invalidation
Secrets generated prior to the official launch of the Public API cannot authenticate against the Public API endpoints. If you are migrating legacy integrations or using older console keys, you must regenerate your secrets under Settings -> API Keys.
Authentication Failure Behavior
To prevent secret enumeration and security leaks, all authentication failures return an identical 401 Unauthorized HTTP status code and response payload, regardless of the underlying cause (e.g., missing secret, invalid secret, or legacy key):
JSON
{
"code": 401,
"message": "Not Authorized"
}
API Conventions & Semantics
1. Retrieves and Filtered Lists (Handling 404 vs 200)
When retrieving single entities or filtered lists via queries, a missing resource or empty filter result does not return a 404 Not Found. Instead, the API returns an HTTP 200 OK with an empty response body or list.
Best Practice: Always inspect the response payload for the presence of an
idor record array rather than relying solely on the HTTP status code to determine existence.
2. Query Parameters and Filtering
List Filters: Passed via query parameters. Repeatable parameters build array filters:
HTTP
GET /api/v1/parts?ids=101&ids=102
Date Filters: Date parameters support both standalone dates and explicitly bounded ranges using range brackets:
HTTP
GET /api/v1/orders?createdAt[from]=2026-01-01T00:00:00Z&createdAt[to]=2026-03-31T23:59:59Z
3. Record Updates (Whole-Record Replacement)
Updates across the Public API are whole-record replacements (PUT semantics), not partial patches (PATCH semantics).
Omitting any field required by the underlying entity schema will result in an HTTP
400 Bad Requesterror explicitly naming the missing required field. Ensure the complete schema payload is supplied during update calls.
4. Downstream Error Pass-Through and Support Tracing
When a downstream microservice or internal module encounters an error, the Public API passes the error response through verbatim:
The response status code and error
code,message, andtypematch the origin error.Diagnostic tracking headers are attached to the response:
x-error-source: Identifies the failing downstream service.x-error-source-request-id: Contains the unique request identifier.
Support Tip: Always record and quote the x-error-source and x-error-source-request-id header values when opening support tickets with the AMFG engineering team.
5. Metering and Rate Limits
Metering: Every authenticated call is metered and logged against your account workspace.
Rate Limits: In
v1of the Public API, we rate-limit to 100/minute. Hence, please make sure to implement reasonable request throttling to optimize network efficiency and data throughput.
Entity Semantics
For complete schema definitions, entity field structures, and data types, refer to the AMFG Engine API Reference documentation.