Multi-tenancy

Hypemarket is multi-tenant. The top-level tenant is an Organization. Users join organizations via memberships, which carry a role (member or admin).

URL shape

Most endpoints are scoped to an organization via the URL:

/organizations/:organization_id/...

The token authenticates the user; the URL identifies the organization. The user must be a member of that organization or the request returns:

• 404 Not Found — the org doesn’t exist for you
• 403 Forbidden — membership found but the action isn’t permitted by your role

User-scoped endpoints

A separate /me/... namespace covers resources that belong to a user directly, not an organization:

• /me/access_tokens
• /me/address
• /me/notifications
• /me/notification_settings
• /me/social_accounts

Roles

Each membership has a role:

Role	Can read	Can mutate organization resources
member	✓	✗ (read-only on most resources)
admin	✓	✓

The organization owner is an admin who additionally cannot be removed or demoted.

Picking the right organization

Most agents should:

1. GET /organizations.json to list the organizations the user belongs to
2. Let the user pick (or, for single-org users, auto-select)
3. Cache the selected organization_id for the session
4. Prepend it to every organization-scoped URL

For the structure of an Organization object, see the Organizations reference.