Document Seam workspace scope

[razor-x]

Now that we document each auth method, and this landed in blueprint, we can document which endpoints require a workspace ID.

From a documentation perspective, this really only affects the "Personal access token" type. I am thinking we can update this line to say something like "Personal access token with SeamWorkspace-Id" or "Personal access token without SeamWorkspace-Id"

I'm not sure the best way to communicate this though. Most endpoints require SeamWorkspace-Id, so it might be less noisy to indicate when SeamWorkspace-Id is optional or must be omitted instead. For example /workspaces/create cannot use SeamWorkspace-Id with /workspaces/list` can use it or not.

[razor-x]

@DebbieAtSeam do you have a recommendation here?

[DebbieAtSeam]

@razor-x Is SeamWorkspace-Id the actual param name? I'm asking because this topic uses different param names. Is this topic out of date?

Either way, I'd suggest adding a child bullet of PAT in the auth methods that has a set of possible strings.

Must also include SeamWorkspace-Id.
(Or would it be
Must also include SeamWorkspace-Id header.
?)

Can also include SeamWorkspace-Id.

Must omit SeamWorkspace-Id.

[razor-x]

Seam-Workspace-Id is a header that must be sent for most endpoints when using a personal access token. This translate to certain usage patterns in the various SDKs.

[DebbieAtSeam]

@razor-x so is the aforementioned topic incorrect?

[razor-x]

I doubled checked and seam-workspace is correct and what we use in the SDKs, not Seam-Workspace-Id

[DebbieAtSeam]

Thanks, @razor-x! Here's my suggestion...

Authentication Methods

• API key
• Client session token
• Personal access token
  • Must also include seam-workspace. <-- One of these three strings
  • Can also include seam-workspace.
  • Must omit seam-workspace.

We should doc the possible header params somewhere too and then link from seam-workspace to that place.

[razor-x]

Thanks, @razor-x! Here's my suggestion...

Authentication Methods

* API key

* Client session token

* Personal access token
  
  * Must also include `seam-workspace`. <-- One of these three strings
  * Can also include `seam-workspace`.
  * Must omit `seam-workspace`.

We should doc the possible header params somewhere too and then link from seam-workspace to that place.

I would change "Can also include seam-workspace." to "Can optionally include seam-workspace."

The message is a bit more subtle though. First, if we say "seam-workspace" we should ideally clarify with "seam-workspace header in the request." However, there are actually a few ways to make bounded vs unbounded requests

1. If not using an SDK: send (or not send) the seam-workspace header.
2. If using a new SDK: Use the SeamMultiWorkspace class for making requests unbound to a workspace (see https://github.com/seamapi/javascript?tab=readme-ov-file#interacting-with-multiple-workspaces)
3. If using a legacy SDK: Pass workspace_id (or env var or similar) to the Seam class to make bounded requests.
4. Seam CLI: should really handle this automatically via the prompts / config. Safe to ignore the use case for now.

[DebbieAtSeam]

I would change "Can also include seam-workspace." to "Can optionally include seam-workspace."

So if you feel strongly about including "optionally," that's fine, but "can" implies that it's optional, and "also" implies that it must accompany using a PAT.

The message is a bit more subtle though. First, if we say "seam-workspace" we should ideally clarify with "seam-workspace header in the request."

OK, then how about this?

• API key
• Client session token
• Personal access token
  • Must also include the seam-workspace header in the request. <-- One of these three strings
  • Can also include the seam-workspace header in the request.
  • Must omit the seam-workspace header from the request.

However, there are actually a few ways to make bounded vs unbounded requests

Can the generator handle generating different versions of this text for the HTTP API ref and the various SDK refs?

1. If not using an SDK: send (or not send) the seam-workspace header.

The case modeled above

2. If using a new SDK: Use the SeamMultiWorkspace class for making requests unbound to a workspace (see https://github.com/seamapi/javascript?tab=readme-ov-file#interacting-with-multiple-workspaces)

When we get to the point where we're thinking about generating SDK refs, we'll need to figure out how to handle this difference for the SDKs vs. HTTP API. Ideally, this explanation would replace the "Must omit..." text

3. If using a legacy SDK: Pass workspace_id (or env var or similar) to the Seam class to make bounded requests.

Again, this explanation should replace the "Can" and "Must include" strings in the SDK refs for the legacy SDKs.

4. Seam CLI: should really handle this automatically via the prompts / config. Safe to ignore the use case for now.

No text needed here, right?

[razor-x]

Ok, let's just focus on the http header case then for now. I agree this falls more into the general problem of SDK / API gen differences.

For the language, happy to keep the original suggestion. I just tend to personally filter out also as a filler word when reading docs vs. stronger language like optional and required. You can take this as personal feedback from my own experience reading these lines.