API authorization

Authentication identifies the caller. Authorization determines whether that caller can read or change a resource in the current team and project context.

Permission checks

Biztraak evaluates the authenticated identity together with team membership, role permissions, project or component ownership, explicit grants, and the operation being requested. A token alone does not grant access to another team’s resources.

For API and GraphQL operations, a request can fail when:

• the caller is not authenticated
• the caller is not a member of the resource’s team
• the caller lacks the required read, write, execute, or administrative permission
• the resource is restricted and the caller is not its owner or explicitly granted access
• the selected provider, billing state, or workflow does not allow the operation

What to send

Authorization is evaluated from the authenticated token and the request target. Include the team, project, component, provider, or workflow identifier required by the operation. do not infer access from a client-side route or identifier alone.

For automation, use a dedicated identity with only the permissions required for the workflow. A service account or API token still has to belong to the correct tenant and role. it does not bypass ownership, explicit component grants, billing checks, or workflow gates.

Common failures

• 401 Unauthorized: the token is missing, expired, malformed, or issued for an unaccepted audience or issuer.
• 403 Forbidden: the identity is valid but lacks the required team, project, component, provider, or operation permission.
• 404 Not Found: the resource does not exist or is intentionally hidden by the caller’s tenant/resource visibility boundary.

GraphQL reports many authorization failures through the response errors array, while REST endpoints use HTTP status codes and may return ProblemDetails. See API errors.

Example authorization flow

1. The caller sends an authenticated request.
2. Biztraak resolves the current team and applies tenant filters.
3. The relevant role and capability permissions are evaluated.
4. Resource-specific ownership or grant checks run when required.
5. The operation succeeds or returns an authorization failure without exposing the protected resource.

Best practices

• Grant the least privilege required for the workflow.
• Use separate service accounts for automation instead of personal credentials.
• Do not put tokens or credentials in source code, URLs, screenshots, or documentation.
• Review team roles, component grants, and audit records when access changes.

See Authentication, Roles, and Audit Logs for related guidance.