Skip to content
CHAMPREPCHAMPREPCHAMPREP Docs

API Gateway overview

The CHAMPREP API Gateway is the public entry point for supported platform integrations. It validates credentials, checks scopes and service access, enforces current usage controls, and routes accepted requests to the relevant CHAMPREP service.

Base URL

Section titled “Base URL”
https://api.champrep.com/v1

Curated public routes are versioned under /v1. Use the complete HTTPS URL in server applications and use environment configuration rather than scattering the base URL throughout your code.

First authenticated request

Section titled “First authenticated request”

Create a scoped key in API Keys, then pass it as a bearer credential:

Terminal window
curl --fail-with-body \
  --header "Authorization: Bearer $CHAMPREP_TOKEN" \
  --header "Accept: application/json" \
  https://api.champrep.com/v1/auth/whoami

Never place a real key in source control, a browser bundle, a mobile binary, a support message, or documentation. Use a server-side secret manager for deployed integrations.

Request conventions

Section titled “Request conventions”
  • Send and accept JSON unless an endpoint explicitly describes another media type.
  • Use ISO 8601 timestamps with an explicit timezone for date and time values.
  • URL-encode path and query values.
  • Keep the bearer credential in the Authorization header.
  • Treat identifiers as opaque strings; do not infer their format or construct them locally.
  • Use the curated /v1 routes in the service endpoint reference.

Official SDKs may use Gateway compatibility routes while a service is being migrated to a curated /v1 contract. That compatibility layer is for the SDK; new direct integrations should not copy backend-private paths from browser traffic or SDK internals.

Response envelopes

Section titled “Response envelopes”

Successful Gateway-composed responses use this shape:

{
  "success": true,
  "data": {}
}

Gateway errors use this shape:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "A safe explanation of the error.",
    "status": 400
  }
}

Some proxied service responses retain their service-specific data envelope. Always check the HTTP status first, then read success, data, or error when present. See errors, limits, and retries for portable error handling.

Authentication and authorization flow

Section titled “Authentication and authorization flow”

Every service request is evaluated in order:

  1. The Gateway validates the API key and any configured IP restrictions.
  2. The current Gateway usage window is checked.
  3. API Gateway access is checked for the active plan and profile.
  4. Destination-service access is checked.
  5. The key’s scope is compared with the route and HTTP method.
  6. The destination service applies its own role, organization, resource, and quota checks.

A 403 can therefore mean that the key is valid but the active scope, role, service access, plan, organization policy, or resource permission does not allow the operation.

Versioning

Section titled “Versioning”

The first URL segment is the major API version. Additive response fields and new endpoints can appear within a major version. Integrations should ignore unknown fields and should not rely on undocumented fields or ordering.

Use GET /v1/version for public Gateway version information. Plan migrations to a future major version explicitly rather than rewriting /v1 paths at runtime.

Next steps

Section titled “Next steps”