Format grant 404 workspace_not_found: only team handles resolve

404 workspace_not_found on POST /v1/formats/{handle}/{slug}/grants means the value in workspace does not resolve to a team workspace. A personal user handle never resolves, because sharing a Format is workspace to workspace, never to a person. Pass the invitee's team handle, or its org_... id.

How the value is resolved

The API reads the workspace field in two ways. If it starts with org_, it is taken as the workspace id as is and no handle lookup happens. Anything else is lowercased and looked up in the handle registry, and the match must be a team, not a user.

A handle that exists but belongs to a person gives the same workspace_not_found as one that does not exist at all. That is intentional: it avoids confirming whether a given person handle is registered.

Do not confuse it with format_not_found

Both are 404s on the same call, and they point at different values. format_not_found says the Format address in the path did not resolve for your key: wrong handle, archived, or you used a personal key against a team Format. workspace_not_found says the Format was fine and the invitee was not.

Check the path first, then the body. If the Format address were wrong, you would not have reached the invitee lookup at all.

A quick way to fix it

Ask the partner for the handle shown on their team workspace, not their own profile handle. If they send an org_ id, use that, because it also survives a later rename of the handle.

For the revoke and role calls, the same rule applies to the {workspace} path segment, which accepts a team handle or an org id.

Checking the handle before you call

There is no public endpoint that tells you whether a handle is a team or a person, by design. The reliable check is human: the partner opens their workspace switcher and reads the team handle there. If you are building an onboarding form for partners, label the field Team handle and show the example format, so people do not paste their personal username.

A second source of confusion is case and whitespace. The value is trimmed and lowercased before lookup, so Kiwi and kiwi behave like kiwi, but an at-sign prefix is part of the string and will fail the lookup. Strip a leading at-sign in your form if your users type one.

Finally, remember the body bounds. Two to 39 characters is the schema range for workspace, so a one-letter value is rejected before any lookup happens, and that is a validation error rather than this 404.

Limits

The error is not retryable and the OpenAPI example marks it as a fix-the-input case. If handle resolution is not configured in an environment, the API returns a 503 account_handles_unavailable instead, which is a deployment issue rather than a typo.