Every request carries a role, decided when you log in. The role controls two things: which endpoints you may call, and which sensitive fields you are allowed to see. Okouro also has a team-leader capability that is a relationship, not a role; it is what gives every role outside the business viewers - admin, operations, and executive - their team powers.

The four roles

A user has exactly one role, returned as the role field on the user object:

When you sign up you become the account’s admin. The three business viewers - admin, operations, and executive - each see and decide on every consultant, timesheet, time-off request, and expense of the account. A user named as somebody’s manager gains team-leader powers on top of their role (below); that is how every other role reaches beyond its own records.

What each role can do

Rather than memorise a matrix, use the status codes as your guide:

• 403 Forbidden means your role is not allowed to call that endpoint at all, or is not allowed for that specific record.
• 404 Not Found means the record exists outside your scope, or not at all; Okouro does not distinguish the two.

Some concrete rules that recur across the guides:

• Validate or reject a timesheet: admin, operations, or executive, or the consultant’s team leader.
• Approve or reject time off: admin, operations, or executive, or the consultant’s team leader.
• Approve or reject an expense: admin, operations, or executive, or the requester’s team leader.
• Pay an expense: admin or operations.
• Update a mission budget: admin only.
• Read staffing KPIs: admin or executive.
• Read mission-budget KPIs: admin, operations, or executive.

On the three decision rules above, separation of duties holds: a non-admin caller - team leader or business viewer alike - never decides a record of their own linked consultant profile; only an admin can.

Team leaders

A user who is named as the manager_id of one or more consultants becomes a team leader for those consultants. This is orthogonal to role: an operations user can be a team leader, and so can another consultant.

The manager_id relationship is what gives the roles outside the business viewers their team powers: a consultant team leader can validate subordinates’ timesheets, approve or reject subordinates’ time off and expenses, and act on their behalf. Their reach is limited to the consultants they manage plus their own, and they never gain these powers over their own records. The business viewers are not narrowed this way: admin, operations, and executive reach every consultant of the account whether or not they manage anyone. operations and executive keep only the separation-of-duties exclusion - they cannot decide the records of their own linked consultant profile.

You can tell whether the current user manages anyone from GET /auth/me: is_manager is true when the user manages at least one consultant.

Field-level visibility

Two money fields are sensitive and are hidden from the consultant role:

A hidden field is returned as null, never removed from the response. So the JSON shape is stable across roles; only the value changes. For example, the same assignment looks different depending on who asks:

{ "id": "...", "consultant_id": "...", "billing_rate": "900.00", "status": "active" }

{ "id": "...", "consultant_id": "...", "billing_rate": null, "status": "active" }

The second response is what a consultant receives. Margin figures on mission budgets and quote profitability follow the same rule (masked from consultant).

Account isolation

Every record belongs to an account (your tenant). A token only ever reaches records in its own account; there is no way to address another account’s data, and cross-account reads return 404. You never pass an account id on requests; it is derived from your token.

Designing around roles

• Treat 403 as “wrong role”, not “transient error”; do not retry.
• Expect sensitive numeric fields to be null for consultant-role tokens, and branch your UI or logic on that rather than assuming a number is always present.
• If you need to act on a subordinate’s record with a consultant token, the acting user must be that record’s manager; a matching role alone is not enough. The business viewers (admin, operations, executive) act on any record of the account - except, for non-admins, the records of their own linked consultant profile.

See Track time, Request time off, and Manage expenses for the role split in each flow.