API Reference

Core conventions for working with the Configo API — versioning, authentication, request format, and error handling.

Base URL

All API requests are made to:

https://configo.org/api

API versioning

The Configo API is versioned via the URL path. The current and only available version is v1:

https://configo.org/api/v1/...

Authentication

The Configo API uses OAuth 2.0. Authenticate your requests by including an access token in the Authorization header as a Bearer token:

Authorization: Bearer <access_token>

Requests without a valid token, or with an expired or revoked token, will receive a 401 Unauthorized response.

Scopes

Access tokens are issued with one or more scopes, which determine what parts of the API the token can access. Every request is checked against the scopes required by the endpoint — all required scopes must be present on the token, not just one of them.

Scope	Grants access to
`identify`	The authenticated user's profile, connected accounts, referrals, and locale
`billing`	Subscription, billing history, and tariff information
`projects`	Project details and project-level settings (roles, members, statuses)
`orders`	Orders within a project
`contacts`	Contacts within a project, including contact fields and activity logs
`materials`	Materials within a project
`configurators`	Configurators within a project, and public configurators in the showcase
`products`	Products within a project
`reports`	Analytics and reporting data within a project
`files`	Uploading, retrieving, and deleting files

Most project-scoped endpoints (orders, contacts, materials, configurators, products, reports) require both the projects scope and the specific resource scope together, since access is evaluated in the context of a project.

Trusted applications

Some endpoints — such as managing sessions, registered apps, support tickets, and account deletion — are restricted to * trusted applications* rather than a specific scope. A trusted application is one explicitly granted elevated access by Configo, separate from the standard OAuth consent flow. If your integration needs access to these endpoints, contact Configo support.

Request format

User-Agent

All requests must include a User-Agent header identifying the client library and its version:

User-Agent: ConfigoClient (library, version)

Content-Type

Requests that include a body must specify a valid Content-Type header:

application/json
application/x-www-form-urlencoded
multipart/form-data

HTTP methods

The API uses standard HTTP methods to indicate the action being performed:

Method	Action
`GET`	Retrieve one or more resources
`POST`	Create a new resource
`PUT`	Replace a resource entirely
`PATCH`	Update part of a resource
`DELETE`	Delete a resource

Response codes

Code	Meaning
`200 OK`	The request completed successfully.
`201 CREATED`	The resource was created successfully.
`204 NO CONTENT`	The request completed successfully but returned no content.
`304 NOT MODIFIED`	The resource was not modified; no action was taken.
`400 BAD REQUEST`	The request was malformed or could not be understood.
`401 UNAUTHORIZED`	The `Authorization` header is missing or invalid.
`403 FORBIDDEN`	The token does not have permission to access this resource.
`404 NOT FOUND`	The requested resource does not exist.
`405 METHOD NOT ALLOWED`	The HTTP method is not supported for this endpoint.
`409 CONFLICT`	The resource already exists.
`429 TOO MANY REQUESTS`	You are being rate limited.
`502 GATEWAY UNAVAILABLE`	No gateway was available to process the request. Wait and retry.
`5xx SERVER ERROR`	An error occurred on Configo's side. These are rare.

Endpoints under /widget use a separate authentication scheme, intended for embedding Configo on a public-facing website rather than for OAuth-based integrations. These requests are authenticated with a project-specific widget token, passed via the x-widget-token header:

x-widget-token: <jwt>