Skip to content

Authentication and scopes

Okatana External API calls use an organization-scoped bearer credential.

The SDK adds this header automatically:

Authorization: Bearer oka_public.secret
Accept: application/json

The token is configured on Configuration. Per-request code cannot override Authorization through the low-level client.

Scope enum

The Scope enum contains the current scope set:

use Newfoundcodes\Okatana\Scope;

Scope::OrganizationRead->value;       // organization:read
Scope::ProjectsRead->value;           // projects:read
Scope::ProjectsWrite->value;          // projects:write
Scope::BoardsRead->value;             // boards:read
Scope::BoardsWrite->value;            // boards:write
Scope::TicketsRead->value;            // tickets:read
Scope::TicketsWrite->value;           // tickets:write
Scope::CommentsWrite->value;          // comments:write
Scope::AnalyticsRead->value;           // analytics:read
Scope::DocumentsRead->value;           // documents:read
Scope::DocumentsWrite->value;          // documents:write
Scope::DocumentCommentsWrite->value;   // document_comments:write
Scope::NotificationsWrite->value;      // notifications:write
Scope::All->value;                     // *

The server is authoritative for authorization. The SDK does not make client-side authorization decisions.

Credential isolation

Use separate credentials for separate workloads. Minimum-scope credentials reduce the impact of token disclosure.

Secret handling

Do not include credentials in:

  • source repositories;
  • exception messages;
  • structured logs;
  • ticket descriptions or document content;
  • shell history copied into issue reports;
  • CI output.

The logger metadata in the SDK excludes token and request body content.