How to design REST API for SaaS with multiple “companies” per account

Question

I am currently working on a SaaS for companies, to manage their business data (employees, invoices, orders, products, ...). The current API design is as following:

GET /employees?limit=10&offset=0

GET /employees/ID

POST /employees

and so on, for every model. In addition you can apply more filters with query parameters.

Until now I checked to which company the logged in account belongs. However now I want that an account can be a "member" in multiple organisations. Eg if the company using the platform hires an "expert", they should be able to grant his account access (make him a member).

The question: How should i implement this in the API design? I've come up with three solution, but don't really know which one is best practice.

Solution 1:

GET /ORGANISATION-ID/employees?limit=10&offset=0

Solution 2:

GET /employees?limit=10&offset=0&organidationId=ORGANISATION-ID

Solution 3:

The URI stays the same, but a Header is set:

|----------------|------------------------|
| Header name    | Value                  |
|----------------|------------------------|
| Authentication | Bearer TOKEN           |
| Organisation   | ID     ORGANISATION-ID |
|     ...        |         ...            |
|----------------|------------------------|

Note : The Authentication header is always set.

I personally thing solution number 3 is the most elegant, but I am not sure if it's inappropriate to use headers for this. Solution 2 is confusing i think, and solution 1 would cause all endpoints to start with the organisation id, which isn't very nice.

Answer 1

Generally I find that the best way to handle this for every path in your API to represent a single resource.

To me that means that, in your case, everything should be namespaced under an organization:

https://api.example.org/org/[orgid]/employees

This way it's very obvious for a member of multiple organizations that there are multiple employee lists.

An similar public example might be github. Everything in github is either A) namespaced under a user B) namespaced under an organization or C) is a top-level github endpoint.