Security

Secret handling

Keep API keys in an OS secret store, cloud secret manager, workload identity system, or protected environment variable. Never commit keys or write them into application logs. Do not put them in ticket comments, documents, CI output, exception text, or URLs.

Least privilege

Create separate credentials per workload and grant only the scopes required by that workload. Document-read credentials are particularly sensitive because organization-level document access can include drafts exposed by the external contract.

URL boundary

The SDK requires an explicit HTTP(S) base URL. Absolute URLs passed to the low-level request API and server pagination links are validated against the configured API origin and /api/v1 path before the SDK sends its bearer credential.

HTML content

Ticket/document descriptions and comments accept HTML. Okatana sanitizes rich content server-side, but producers should still generate minimal, predictable HTML. Do not use HTML fields as a channel for secrets.

Logs and exceptions

API exceptions preserve the response body to support diagnosis. Treat those bodies as application data. Do not indiscriminately forward full exception bodies to public telemetry or user-visible error pages.

Redirects and absolute URLs

The default HTTP handler does not follow redirects automatically. Absolute low-level request URLs and paginator URLs must use the same scheme, host, port, and configured /api/v1 base path before the SDK attaches the bearer token. This makes the destination boundary explicit.