Skip to content

Production operations

This guide describes operating an application with the SDK. It is not a replacement for server administration guidance.

Configuration contract

Treat OKATANA_URL and OKATANA_TOKEN as deployment configuration. The URL identifies the Okatana deployment. The token identifies an organization-scoped integration principal.

Environment shape:

OKATANA_URL=https://pm.example.net
OKATANA_TOKEN=oka_public.secret
OKATANA_ORG=01...

The SDK appends /api/v1 if the URL omits it.

Separate credentials by workload

Do not share one token across unrelated systems. Examples:

  • reporting worker: project/ticket/document read and analytics read;
  • release worker: project read, board read, ticket write, comment write, notification write;
  • documentation publisher: document read/write and document-comment write.

This isolates failures and produces clearer audit trails.

Retry ownership

Assign a single retry owner. If an external queue or workflow engine retries jobs, disable SDK retries via RetryPolicy::disabled(). Nested retries multiply requests.

Write operations lack an idempotency key. Store returned IDs immediately. If a create operation fails ambiguously, check a stable marker before replaying.

Rate-limit handling

A 429 status throws RateLimitException. The exception provides a parsed Retry-After value if present. Default retries apply only to reads.

For exports:

  1. use the maximum per_page allowed;
  2. process sequentially;
  3. checkpoint the current page or object;
  4. back off when rate-limited;
  5. avoid caching all pages in memory.

Logging

Inject a PSR-3 logger for request telemetry:

$client = new OkatanaClient(
    configuration: $configuration,
    logger: $logger,
);

The SDK logs request method, path, status, attempt count, and duration. It omits the API token and JSON bodies.

Do not log authorization headers or payloads to HTTP debug logs without reviewing data handling policies.

Timeouts

The Guzzle client applies the configured request timeout and limits connection timeouts to ten seconds. If injecting a PSR-18 client, set timeouts on the transport directly.

Set timeouts based on workload requirements. Command-line exports support longer timeouts than web requests.

Queue workers

For write operations:

  • log the intent before sending;
  • record the Okatana ULID upon success;
  • use a business marker to reconcile creates;
  • avoid blind POST replays;
  • treat 401, 403, and 422 as client errors;
  • handle 429 and 5xx per the worker retry policy.

Health checks

Do not use mutations as health checks. Use the smallest authorized read endpoint, such as organization read.

A health endpoint must distinguish:

  • transport failure;
  • authentication failure;
  • authorization failure;
  • server error;
  • valid API response.

Exclude tokens and exception payloads from public endpoints.

Credential rotation

Rotation requires configuration changes:

  1. issue a replacement credential with identical or reduced scopes;
  2. deploy the secret;
  3. execute a read/write verification test;
  4. revoke the previous credential;
  5. verify the previous credential fails.

Upgrade procedure

When upgrading the SDK or deployment:

  1. diff the deployed OpenAPI document against resources/openapi.yaml;
  2. run composer test;
  3. run composer analyse;
  4. execute an integration test on a non-production deployment;
  5. verify pagination behavior and compatibility parameters;
  6. deploy per application release processes.