Optional pre-login step. Returns which login methods are available for an email address without revealing whether it exists.

{
  "email": "user@example.com"
}

{
  "password": true,
  "tfa": "totp"   // omitted when no TFA is active
}

Primary login. Returns tokens used for all subsequent authenticated requests.

{
  "email": "user@example.com",
  "secret": "your-password",
  "tfaCode": "123456"   // required when account uses TFA
}

{
  "accessToken": "<JWT>",
  "accessTokenExpiresAt": 1735000000,
  "refreshToken": "<refreshToken>",
  "refreshTokenExpiresAt": 1737000000
}

Refresh the current access token. Also accessible as GET /auth/refresh-token.

x-refresh-token: <refreshToken>

// Same shape as POST /auth/login

Terminate the current session. Revokes the refresh state for the current user session.

{}

Fetches a combined view of the caller's user record, organizations, and organization profiles. Use this to resolve profileId values required by downstream requests. Also accessible as GET /user/profile/organization.

x-active-organization-id: <organizationId>  // pin context when user belongs to multiple orgs

{
  "user": { /* signed-in user record + permissions */ },
  "organizations": [ /* orgs the user can access */ ],
  "profiles": [ /* organization profiles tied to those orgs */ ]
}

Change the current user's password.

{
  "password": "new-password",
  "oldPassword": "current-password"
}

Create a two-factor authentication method for the current user.

{
  "password": "current-password",
  "type": "totp"
}

Activate a previously created two-factor authentication method.

{
  "tfaCode": "123456"
}

Disable a two-factor authentication method.

{
  "tfaId": "<tfaId>",
  "password": "current-password"
}

Remove a two-factor authentication method.

{
  "tfaId": "<tfaId>",
  "password": "current-password"
}

List configured two-factor authentication methods for the current user.

List organizations available to the authenticated user.

{
  "organizations": [ /* array of orgs the caller may access (RBAC-derived) */ ]
}

Create an API key for a given organization profile.

{
  "profileId": "<profileId>"
}

List API keys for a given organization profile.

{
  "profileId": "<profileId>"
}

Set or remove feature flags on an organization profile.

{
  "profileId": "<profileId>",
  "flags": [
    { "flag": "GHGP", "value": true },
    { "flag": "BOOK_AND_CLAIM", "value": null }
  ]
}

List users associated with the current organization.

{}

Invite a user to an organization.

{
  "organizationId": "<organizationId>",
  "email": "new.user@example.com",
  "firstName": "First",
  "lastName": "Last"
}

Resend an invitation for an existing organization user.

{
  "organizationId": "<organizationId>",
  "userId": "<userId>"
}

Assign organization-level roles to a user.

{
  "organizationId": "<organizationId>",
  "userId": "<userId>",
  "defaultRoleCodes": ["default.organization.admin"],
  "roleCodes": ["basic.admin"]
}

Assign organization-profile-level roles to a user.

{
  "profileId": "<profileId>",
  "userId": "<userId>",
  "roleCodes": ["basic.admin"]
}

Create a business location associated with an organization profile.

{
  "profileId": "<profileId>",
  "name": "Location Name",
  "type": "buying",
  "basin": "Permian",
  "isDirectConnection": false,
  "preferredSuppliers": ["Antero"],
  "coordinates": {
    "latitude": 31.972096,
    "longitude": -83.760640
  },
  "address": {
    "country": "US"
  }
}

Update a business location.

{
  "_id": "<businessLocationId>",
  "basin": "Permian",
  "isDirectConnection": true,
  "preferredSuppliers": ["QB"],
  "name": "Updated Location",
  "address": {
    "country": "US",
    "state": "NY"
  },
  "status": "active"
}

Return details for a business location.

{
  "_id": "<businessLocationId>"
}

List business locations for a given profile.

{
  "profileId": "<profileId>"
}

Upload up to 5 files (10 MB each). Use the returned _id values as temporary document references in subsequent request bodies.

Content-Type: multipart/form-data
Field name: files  (repeat for each file, up to 5)

{
  "files": [
    { "_id": "<uuid>", /* ...file record */ }
  ]
}

Download a file by UUID. Caller must own the file or have permission on the network transaction it belongs to. Returns 403 otherwise. Non-PDF files receive Content-Disposition: attachment.

List energy wallets accessible to the caller's producer / base profiles.

{
  "wallets": [ /* array of energy wallets */ ]
}

Aggregated account balance summary for a wallet. Supports filtering by energy type, token type, status, vintage year/month, carbon intensity, and more.

{
  "walletId": "<walletId>",
  "isPublic": false,
  "energyType": "natural-gas",   // natural-gas | natural-gas-pipeline | methanol | renewable-natural-gas | solid-fuel
  "tokenType": "QET",            // QET | CET
  "status": "enabled",           // enabled | disabled
  "year": 2024,
  "month": 6,
  "maxCarbonIntensity": 10.5,
  "uom": "MMBtu"
}

Paginated list of energy account summaries in a wallet. Accepts the same filter fields as summary/accounts.

{
  "walletId": "<walletId>",
  "paginate": { "skip": 0, "limit": 50 }
}

{
  "energyAccounts": [ /* paginated array of account summaries */ ]
}

Return a single energy account summary by UUID.

{
  "energyAccount": { /* energy account summary record */ }
}

Publish or unpublish energy accounts for market listing, setting a price for public accounts.

{
  "walletId": "<walletId>",
  "accountIds": ["<accountId>"],
  "isPublic": true,
  "price": { "amount": 5.00, "currency": "USD" }
}

Paginated list of ledger transactions for a wallet.

{
  "walletId": "<walletId>",
  "paginate": { "skip": 0, "limit": 50 }
}

{
  "transactions": [ /* paginated ledger transactions */ ]
}

Paginated list of public energy accounts. All filter fields are optional and can be combined freely.

{
  "energyType": "renewable-natural-gas",
  "tokenType": "QET",
  "year": 2024,
  "month": 6,
  "standardType": "OGCI",
  "basin": "Permian",
  "maxCarbonIntensity": 10.5,
  "paginate": { "skip": 0, "limit": 50 }
}

{
  "energyAccounts": [ /* public energy account summaries */ ]
}

Return a single public energy account by UUID. Only public accounts are returned.

{
  "energyAccount": { /* public energy account summary */ }
}

Aggregated balance summary for a specified owner's public accounts.

{
  "ownerId": "<ownerId>"
}

{
  "name": "My Minting Contract",
  "referenceIds": ["<energyAssetId>"],   // required, non-empty
  "operationContractType": "natural_gas_produce_minting",  // or natural_gas_transportation_minting
  "workflowId": "<workflowId>",           // optional
  "buyer": { "profileId": "<profileId>", "walletId": "<walletId>" }  // optional
}

{
  "contract": { /* created minting contract record */ }
}

All filter fields are optional. Also accessible as POST /network/minting/list via the gateway.

{
  "status": "draft",        // draft | awaiting_approval | processed | canceled
  "energyType": "natural-gas",
  "tokenType": "QET",       // QET | CET
  "operationContractType": "natural_gas_produce_minting",
  "issuerProfileId": "<profileId>",
  "buyerProfileId": "<profileId>",
  "createdAtFrom": "2024-01-01T00:00:00Z",
  "createdAtTo": "2024-12-31T23:59:59Z",
  "paginate": { "skip": 0, "limit": 100 }  // limit max 2500
}

{
  "contracts": [ /* minting contract summaries */ ]
}

Return the full minting contract record by UUID.

{
  "contract": { /* full minting contract record */ }
}

Aggregated cohort (token-level) breakdown for a minting contract.

{
  "_id": "<mintingContractId>",
  "energyTokenId": "<energyTokenId>"
}

{
  "cohortSummary": { /* token-level summary */ }
}

{
  "_id": "<mintingContractId>"
}

{
  "contract": { /* removed minting contract record */ }
}

Initiate a push transaction. Caller owns the source wallet.

{
  "fromProfileId": "<profileId>",
  "fromWalletId": "<walletId>",  // optional; resolved from profile when omitted
  "toProfileId": "<profileId>",
  "toWalletId": "<walletId>",    // optional
  "isSecure": false               // true = two-step secure push
}

{
  "networkTransaction": { /* created transaction record */ }
}

Lock energy accounts for an existing push transaction.

{
  "_id": "<transactionId>",
  "quantity": 100,
  "filter": {
    "energyType": "natural-gas",
    "tokenType": "QET",
    "isPublic": false
    // ...additional MarketAccountFilter fields
  },
  "forcePrice": { "amount": 5.00, "currency": "USD" }  // optional
}

Initiate a pull transaction. Caller owns the destination wallet.

{
  "fromProfileId": "<profileId>",
  "fromWalletId": "<walletId>",  // optional
  "toProfileId": "<profileId>",
  "toWalletId": "<walletId>"     // optional
}

{
  "networkTransaction": { /* created transaction record */ }
}

Lock energy accounts for a pull transaction. Only public accounts are eligible — isPublic: true is enforced server-side.

{
  "_id": "<transactionId>",
  "quantity": 100,
  "filter": {
    "energyType": "natural-gas",
    "tokenType": "QET"
  }
}

{
  "walletId": "<walletId>",
  "status": "draft",          // draft | awaiting_approval | processed | canceled
  "transactionType": "push",  // push | pull
  "energyType": "natural-gas",
  "iAmSigner": true,          // when true: only returns transactions where caller is a signer
  "paginate": { "skip": 0, "limit": 50 }
}

{
  "networkTransactions": [ /* paginated list; fee fields cleared for non-payer callers */ ]
}

{
  "_id": "<transactionId>"
}

{
  "networkTransaction": { /* full transaction record */ }
}

{
  "_id": "<transactionId>",
  "energyTokenId": "<energyTokenId>"
}

{
  "cohortSummary": { /* token-level summary */ }
}

{
  "_id": "<transactionId>",
  "contractId": "string",       // optional
  "description": "string",      // optional
  "files": [{ /* FileDto */ }],       // optional; files to attach
  "removeFiles": [{ /* FileDto */ }]  // optional; files to detach
}

{
  "networkTransaction": { /* updated transaction record */ }
}

{
  "_id": "<transactionId>"
}

{
  "_id": "<transactionId>"
}

{
  "_id": "<transactionId>",
  "description": "Cancellation reason"  // optional
}

Signs and submits the transaction for processing. The access token must reflect a completed TFA step (usedTfa: true on JWT payload).

{
  "_id": "<transactionId>"
}

Creates a new intra-transfer in draft status.

{
  "fromProfileId": "<profileId>",
  "fromWalletId": "<walletId>",  // optional
  "toProfileId": "<profileId>",
  "toWalletId": "<walletId>"     // optional
}

{
  "retirement": { /* created intra-transfer record (field name is "retirement") */ }
}

{
  "walletId": "<walletId>",
  "profileId": "<profileId>",    // optional
  "status": "draft",              // draft | awaiting_approval | processed | canceled
  "energyType": "natural-gas",
  "paginate": { "skip": 0, "limit": 50 }
}

{
  "intraTransfers": [ /* paginated list */ ]
}

{
  "_id": "<intraTransferId>"
}

{
  "intraTransfer": { /* full record */ }
}

{
  "_id": "<intraTransferId>",
  "energyTokenId": "<energyTokenId>"
}

{
  "cohortSummary": { /* token-level summary */ }
}

{
  "_id": "<intraTransferId>",
  "quantity": 100,
  "filter": { /* energy account selection criteria */ }
}

{
  "_id": "<intraTransferId>"
}

Delete a draft intra-transfer.

{
  "_id": "<intraTransferId>"
}

Signs and submits the intra-transfer. The access token must reflect a completed TFA step (usedTfa: true on JWT payload).

{
  "_id": "<intraTransferId>"
}

{
  "profileId": "<profileId>",
  "walletId": "<walletId>",  // optional
  "name": "Consumption label"
}

{
  "consumption": { /* created consumption record */ }
}

{
  "walletId": "<walletId>",
  "status": "draft",
  "energyType": "natural-gas",
  "paginate": { "skip": 0, "limit": 50 }
}

{
  "consumptions": [ /* paginated list */ ]
}

{
  "_id": "<consumptionId>",
  "fullCohorts": true  // optional; includes full cohort breakdown when true
}

{
  "consumption": { /* record with associated accounts */ }
}

{
  "_id": "<consumptionId>",
  "energyTokenId": "<energyTokenId>"
}

{
  "cohortSummary": { /* token-level summary */ }
}

{
  "_id": "<consumptionId>",
  "quantity": 100,
  "filter": {
    "ownerId": "<ownerId>",   // optional
    "isPublic": false          // optional; plus other MarketAccountFilter fields
  }
}

{
  "_id": "<consumptionId>"
}

{
  "_id": "<consumptionId>"
}

Signs and submits the consumption record. The access token must reflect a completed TFA step.

{
  "_id": "<consumptionId>"
}

Creates a new retirement in draft status.

{
  "profileId": "<profileId>",
  "walletId": "<walletId>",  // optional
  "name": "Retirement label"
}

{
  "retirement": { /* created retirement record */ }
}

{
  "walletId": "<walletId>",
  "status": "draft",
  "energyType": "natural-gas",
  "paginate": { "skip": 0, "limit": 50 }
}

{
  "retirements": [ /* paginated list */ ]
}

{
  "_id": "<retirementId>",
  "fullCohorts": true  // optional
}

{
  "retirement": { /* record with associated energy accounts */ }
}

{
  "_id": "<retirementId>",
  "energyTokenId": "<energyTokenId>"
}

{
  "cohortSummary": { /* token-level summary */ }
}

{
  "_id": "<retirementId>",
  "quantity": 100,
  "filter": { /* energy account selection criteria */ }
}

{
  "_id": "<retirementId>"
}

Update metadata fields (beneficiary, purpose, reporting period).

{
  "_id": "<retirementId>",
  "purpose": "Scope 1 emissions offset",
  "additionalContext": "Q4 2024",
  "beneficiary": { /* RetirementBeneficiaryDto */ }  // set to null to clear
}

Delete a draft retirement.

{
  "_id": "<retirementId>"
}

Signs and submits the retirement. Triggers certificate generation. The access token must reflect a completed TFA step (usedTfa: true on JWT payload).

{
  "_id": "<retirementId>"
}

Download the PDF retirement certificate once the retirement is processed.

Content-Type: application/pdf  (streaming)

Resolve the retirement record associated with an on-chain token identifier within a specific wallet.

{
  "tokenId": "<energyTokenId>",
  "walletId": "<walletId>"
}

Upload up to 5 files (10 MB each). The returned _id is used as a document._id when creating a production batch.

Content-Type: multipart/form-data
Field name: files  (repeat for each file, up to 5)

{
  "files": [
    { "_id": "<uuid>", /* ...file record */ }
  ]
}

List files attached to a specific entity.

{
  "ownerType": "production_batch",  // user | organization | organization_profile | energy_asset
                                    // production_batch | batch_workflow | network_transaction | retirement
  "ownerId": "<entityId>"
}

{
  "files": [ /* file records for the specified owner */ ]
}

Download a file by UUID. Caller must have permission on the file's owner entity. Returns 403 otherwise.

Download a file attached to a specific energy-wallet token account.

Download a file attached to a specific market token account.

Create a new RNG production batch. Upload the document first using POST /file/temporary-upload and pass the returned _id here.

{
  "name": "Batch label",
  "profileId": "<profileId>",
  "energyType": "renewable-natural-gas",  // renewable-natural-gas | solid-fuel
  "tokenType": "QET",                     // QET | CET
  "document": { "_id": "<temporaryFileUuid>" }
}

{
  "batch": { /* production batch record including _id */ }
}

Fetch full batch details including workflows. Use the relevant item in batch.workflows — its _id is the workflowId required by measurement and minting requests.

{
  "_id": "<batchId>"
}

{
  "batch": { /* batch with workflows, assets, and attached files */ }
}

{
  "profileId": "<profileId>",               // optional; defaults to all caller profiles
  "boundaryIdentifierId": "facility-id",    // optional
  "energyType": "renewable-natural-gas",    // optional
  "vintageDateFrom": "2024-01-01T00:00:00Z",
  "vintageDateTo": "2024-12-31T23:59:59Z",
  "paginate": { "skip": 0, "limit": 50 }
}

{
  "batches": [ /* paginated list visible to caller's issuer profiles */ ]
}

{
  "batchId": "<batchId>"
}

{
  "batchId": "<batchId>"
}

Attach files to the measurement batch step. The files array is required and must be non-empty.

{
  "profileId": "<profileId>",
  "workflowId": "<workflowId>",
  "description": "Optional note",
  "files": [
    { "_id": "<temporaryFileUuid>" }
  ]
}

{
  "profileId": "<profileId>",
  "workflowId": "<workflowId>",
  "description": "Optional note",
  "files": [
    { "_id": "<fileUuid>" }
  ]
}

Approve the measurement batch step. The access token must reflect a completed TFA step.

{
  "profileId": "<profileId>",
  "workflowId": "<workflowId>",
  "description": "Optional approval note"
}

{
  "profileId": "<profileId>",
  "workflowId": "<workflowId>",
  "description": "Optional rejection reason"
}

{
  "profileId": "<profileId>",
  "workflowId": "<workflowId>"
}

{
  "batchId": "<batchId>",
  "tokenType": "QET",
  "scope": { "workflowId": "<workflowId>" }  // optional
}

{
  "energyAssets": [ /* assets sent to the network */ ]
}

Create a minting contract from an approved batch. Use the returned contract._id as mintingContractId in the next step.

{
  "name": "Contract label",
  "batchId": "<batchId>",
  "scope": { "workflowId": "<workflowId>" }  // optional
}

{
  "contract": { /* minting contract; use contract._id as mintingContractId */ }
}

{
  "mintingContractId": "<contractId>"
}

{
  "energyAssets": [ /* minted assets */ ]
}