Skip to main content
API docs by Redocly

CFO OAuth Client Credentials Integration API (1.0.0-dev-pilot)

Download OpenAPI specification:Download

License: LicenseRef-OneClimate-Proprietary

CFO is the OAuth issuer. This DEV pilot uses OAuth 2.0 client credentials with an opaque access token that expires in 15 minutes and has no refresh token.

Store client_secret in the ERP secret store, never place credentials in a query string, and do not share screenshots of Authorization headers. Obtain and use access tokens only from the ERP or another approved server-side integration runtime. Do not enter client secrets or access tokens into browser-based API documentation; the customer documentation is read-only.

Persistence is decided by the grant issued to the client, not by the authentication method. A client whose grant is dry-run only is rejected when it sends dry_run=false; a client whose grant allows persistence may send either value.

Token

Exchange a customer ERP client credential for a short-lived access token.

Exchange OAuth client credentials for an opaque access token

Submit application/x-www-form-urlencoded grant_type=client_credentials with HTTP Basic client authentication from the ERP or another approved server-side integration runtime. Never enter the client secret in browser documentation.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "client_credentials"

Responses

Response samples

Content type
application/json
{
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "scope": "cfo.integration.read cfo.activity_import.dry_run"
}

Discovery

Discover the authority, destinations, facilities, periods and capabilities granted to the client.

Read the OAuth-client scoped context

Authorizations:
CFOAccessToken

Responses

Response samples

Content type
application/json
{ }

List facilities available to this OAuth client now

Authorizations:
CFOAccessToken

Responses

Response samples

Content type
application/json
{ }

List active reporting periods available to this OAuth client now

Authorizations:
CFOAccessToken

Responses

Response samples

Content type
application/json
{ }

List authoritative facility-retention destinations available now

Select only a returned facility-retention pair; never construct a cartesian product.

Authorizations:
CFOAccessToken

Responses

Response samples

Content type
application/json
{ }

List active reporting periods for one available facility

Authorizations:
CFOAccessToken
path Parameters
facility_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{ }

List currently enabled capability codes for one destination and scope

Authorizations:
CFOAccessToken
query Parameters
facility_id
required
string <uuid>
retention_id
required
string <uuid>
scope
required
integer
Enum: 1 2 3

Responses

Response samples

Content type
application/json
{ }

Activity imports

Validate or persist granted activity rows and inspect asynchronous outcomes.

Queue one idempotent activity import (dry-run or persisted, per grant)

Authorizations:
CFOAccessToken
path Parameters
facility_id
required
string <uuid>
header Parameters
Idempotency-Key
required
string <= 128 characters
Request Body schema: application/json
required
schema_version
required
string
Value: "cfo-activity-import-v1"
external_batch_id
required
string
source_system
required
string
retention_id
required
string <uuid>
scope
required
integer
Enum: 1 2 3
dry_run
required
boolean

true validates only; false persists and requires a grant with write_mode=persist

required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "schema_version": "cfo-activity-import-v1",
  • "external_batch_id": "string",
  • "source_system": "string",
  • "retention_id": "e7a9be08-99f5-4db8-91af-2011598cd22f",
  • "scope": 1,
  • "dry_run": true,
  • "rows": [
    ]
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "queued",
  • "phase": "queued",
  • "external_batch_id": "string",
  • "received_rows": 0,
  • "processed_rows": 0,
  • "created_rows": 0,
  • "validated_rows": 0,
  • "skipped_rows": 0,
  • "pending_review_rows": 0,
  • "failed_rows": 0,
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "correlation_id": "string"
}

Read one import job — the authoritative outcome of a submission

Authorizations:
CFOAccessToken
path Parameters
job_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "queued",
  • "phase": "queued",
  • "external_batch_id": "string",
  • "received_rows": 0,
  • "processed_rows": 0,
  • "created_rows": 0,
  • "validated_rows": 0,
  • "skipped_rows": 0,
  • "pending_review_rows": 0,
  • "failed_rows": 0,
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "correlation_id": "string"
}

Read the per-row outcome of an import job

Authorizations:
CFOAccessToken
path Parameters
job_id
required
string <uuid>
query Parameters
cursor
integer
Default: 0

Pass next_cursor from the previous page.

limit
integer
Default: 100

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": 0,
  • "has_more": true
}