API reference

Draft contract · no live API. Generated from OpenAPI 3.1.1, version 1.0.0-draft.

Download the exact YAML. SHA-256: edb36682e0c124e1a67cfc6213ed93dcfa2494e84c63f79181ae7ed12f9851e7.

The first slice has three reads and one delegated journal-draft operation. All hosts below are illustrative. No requests can be sent from this portal.

GET /api/v1/companies — List accessible pilot companies
GET /api/v1/companies/{companyId}/ledger/accounts — List safe account definitions
GET /api/v1/companies/{companyId}/ledger/periods — List period dates and status
POST /api/v1/companies/{companyId}/ledger/journal-drafts — Create an ordinary manual draft as a delegated user

Server definitions

[
  {
    "url": "https://api.sandbox.ginum.example/api/v1",
    "description": "Illustrative synthetic sandbox hostname, not deployed."
  },
  {
    "url": "https://api.ginum.example/api/v1",
    "description": "Illustrative production hostname, not deployed; exposure requires separate approval."
  }
]

Authorization schemes

PKCE S256 is mandatory for delegated clients. Machine credentials have read scopes only. Registration does not grant data access.

{
  "DelegatedOAuth": {
    "type": "oauth2",
    "description": "Authorization Code with mandatory PKCE S256 for all user clients. Exact redirect URI, state and OIDC nonce if requested. Access TTL 300s; ID tokens forbidden at API. Issuer URL is illustrative; final host must preserve existing passkey RP. Token audience is environment-specific ERP API. No implicit/password grant.",
    "x-pkce": {
      "required": true,
      "codeChallengeMethods": [
        "S256"
      ]
    },
    "flows": {
      "authorizationCode": {
        "authorizationUrl": "https://identity.ginum.example/oauth2/authorize",
        "tokenUrl": "https://identity.ginum.example/oauth2/token",
        "refreshUrl": "https://identity.ginum.example/oauth2/token",
        "scopes": {
          "companies:read": "Read permitted company metadata.",
          "ledger.accounts:read": "Read permitted account definitions, no balances.",
          "ledger.periods:read": "Read period dates and status; pending Ledger approval.",
          "ledger.journal-drafts:write": "Create ordinary manual drafts as the consenting user; no submit, approve or post."
        }
      }
    }
  },
  "MachineOAuth": {
    "type": "oauth2",
    "description": "Client credentials, asymmetric private_key_jwt preferred; explicit current tenant/company service read grant, no refresh token and no human impersonation. Access TTL 300s. P1 machine write scopes are neither registered nor issued. Sandbox and production use different issuer/audience/client identities.",
    "flows": {
      "clientCredentials": {
        "tokenUrl": "https://identity.ginum.example/oauth2/token",
        "scopes": {
          "companies:read": "Read permitted company metadata.",
          "ledger.accounts:read": "Read permitted account definitions, no balances.",
          "ledger.periods:read": "Read period dates and status; pending Ledger approval."
        }
      }
    }
  }
}

Schema catalogue

Read all request and response schemas.