Three ways the organization is decided
It’s never guessed. Exactly one of these applies to any request: From the path./v1/organizations/{orgId}/… — the id is right there, and your membership of it is checked.
From the project. /v1/projects/{projectId}/…, which is most of the API. The organization is the project’s — derived, not asserted — and membership of that is what grants access.
From an explicit query parameter. Routes with neither in the path — live SERP lookups, keyword research, trends, domain and backlink lookups. These are billable, so with a user token the organization must be named as org_id:
BAD_REQUEST: “org_id is required. This call is billed to an organization, so it cannot be inferred.”
That third case exists because of a bug in the previous implementation. Routes with no organization in the path resolved it as “the user’s first membership”, from an unordered query — so for users belonging to two organizations, lookups were billed to whichever row came back first, and the plan limit checked was that organization’s too. Guessing is no longer available.
Membership, and what “not a member” looks like
Two checks run:- Are you a member, and have you accepted? An invitation you haven’t accepted is not membership — the row exists to hold the invitation, not to grant access.
- Does the resource actually belong to that organization?
NOT_FOUND, not FORBIDDEN. A 403 would confirm the organization or project exists, which is the fact being protected.
So a 404 doesn’t prove deletion. Check your ids, and check the invitation was accepted, before concluding anything.
Roles are hierarchical
owner ⊃ admin ⊃ member. A check for admin passes for an owner.
Failing a role check is a genuine FORBIDDEN (403), with a message naming what’s required — “This action requires the owner role.” The distinction from 404 is deliberate: you can already see the organization, so hiding it now would only confuse. What you can’t do is this action.
An admin can do everything an owner can except the last two. The role you can give — on an invite or a role change — is
admin or member; owner fails validation for everyone, because the creator is the owner and nobody is made one afterwards.
An invite (POST /v1/organizations/{orgId}/members, with full_name, email and role) works for any address: somebody new gets an account under that name. It emails a link that signs them in and joins them (POST /v1/invitations/{orgId}/accept); until then the membership is pending and grants nothing.
Creating a project requires admin because a project commits the organization to scheduled collection. Projects are unlimited on every plan, but creating one needs a live plan — without one it answers PLAN_REQUIRED (402).
An organization always keeps an owner
Only an owner can change or remove another owner (PATCH /v1/organizations/{orgId}/members/{userId}/role, DELETE /v1/organizations/{orgId}/members/{userId}); an admin who tries gets FORBIDDEN (403). The last owner can’t be demoted or removed by anyone — the request fails with BAD_REQUEST (400), “An organization needs at least one owner.”, rather than leaving an organization nobody can administer. The check runs inside the write, so two owners demoting each other at the same moment can’t both succeed.
Working across organizations
There’s no cross-organization endpoint.- With an API key — one key per organization, selected per request in your client.
GET /v1/organizationsanswers with the key’s own organization, so an integration finds its organization id from its first call. - With a user token —
GET /v1/organizationslists your accepted memberships; loop and issue scoped requests for each.
organization argument.