Query workspace memberships and user profile

The workspace membership endpoints give you read access to everything your authenticated user belongs to: which organizations you are a member of, which one is currently active, a full bundle of a single org’s data, and your own user profile. These are the endpoints that power the Safeclose navigation shell — you can call them directly to bootstrap your integration or to validate membership state before executing org-scoped actions. All endpoints require a valid Bearer token. See Authenticate requests for details.

List memberships

GET /v1/workspace/memberships

Returns every organization the authenticated user is an active member of. Each item in the array combines the membership record, the organization it belongs to (including billing account and counts), and the role assigned to you.

Request headers

string

required

Bearer token from your Clerk session. Example: Bearer eyJhbGc...

Response

Returns a JSON array. Each element has the following shape:

string

required

Membership record ID.

string

required

The authenticated user’s ID.

string

required

Always "ACTIVE" for records returned by this endpoint.

string

required

ID of the organization this membership belongs to.

string

required

ISO 8601 timestamp when the membership was created.

object

required

The organization record.

Show organization properties

string

required

Organization ID.

string

required

Display name of the organization.

string

required

URL-safe slug. Unique across all organizations. Lowercase alphanumeric with hyphens, 2–48 characters.

string

required

User ID of the organization owner. Owners always have all permissions.

string or null

required

Custom brand display name, or null if not configured.

string or null

required

URL to the organization’s logo image, or null if not configured.

string or null

required

Primary brand color as a #RRGGBB hex string, or null if not configured.

string

required

ISO 8601 timestamp when the organization was created.

object or null

required

The organization’s billing account, or null if not yet provisioned.

Show billingAccount properties

string

required

Billing account ID.

string

required

Parent organization ID.

string

required

Current subscription tier. One of "FREE", "STARTER", "PRO", "ENTERPRISE".

string

required

Billing status. One of "NONE", "ACTIVE", "PAST_DUE", "CANCELED".

string or null

required

Stripe customer ID, or null if not connected.

string or null

required

Stripe subscription ID, or null if not on a paid plan.

object

required

Aggregate counts for the organization.

Show _count properties

number

required

Total number of active members.

number

required

Total number of configured locations.

number

required

Total number of roles (built-in and custom).

object

required

The role assigned to you in this organization.

Show role properties

string

required

Role ID.

string

required

Human-readable role name, e.g. "Owner" or "Agent".

string

required

URL-safe slug for the role, e.g. "owner" or "agent".

boolean

required

true for the system-created owner role; false for custom roles.

object

required

A JSON object where each key is a permission key and the value is true or false. See the org permission model for the full list of keys.

Example

curl --request GET \
  --url https://your-api.example.com/v1/workspace/memberships \
  --header 'Authorization: Bearer <your-session-token>'

[
  {
    "id": "mem_01j9z8x7w6v5u4t3s2r1q0p",
    "userId": "user_clerk_abc123",
    "status": "ACTIVE",
    "organizationId": "org_01j9z8aabbccdd",
    "createdAt": "2025-09-01T08:00:00.000Z",
    "organization": {
      "id": "org_01j9z8aabbccdd",
      "name": "Acme Auto Finance",
      "slug": "acme-auto-finance",
      "ownerUserId": "user_clerk_abc123",
      "brandName": "Acme",
      "brandLogoUrl": "https://cdn.example.com/acme-logo.png",
      "brandPrimaryHex": "#1A56DB",
      "createdAt": "2025-09-01T07:50:00.000Z",
      "billingAccount": {
        "id": "bill_01j9z8bbccddee",
        "organizationId": "org_01j9z8aabbccdd",
        "planTier": "PRO",
        "status": "ACTIVE",
        "stripeCustomerId": "cus_AbCdEfGhIjKl",
        "stripeSubscriptionId": "sub_AbCdEfGhIjKl"
      },
      "_count": {
        "members": 8,
        "locations": 3,
        "roles": 4
      }
    },
    "role": {
      "id": "role_01j9z8ccddee",
      "name": "Owner",
      "slug": "owner",
      "isBuiltIn": true,
      "permissions": {
        "orgSettings": true,
        "brand": true,
        "locations": true,
        "roles": true,
        "members": true,
        "billing": true
      }
    }
  }
]

Get active organization ID

GET /v1/workspace/active-org-id

Returns the ID of the organization currently marked active for your session. Safeclose resolves this by looking up the activeOrganizationId stored in your user profile and confirming that you are still an active member. If the stored value is stale (e.g., you were removed), the API clears it and falls back to the first organization in your membership list, alphabetically. Returns null if you have no active memberships.

Request headers

string

required

Bearer token from your Clerk session.

Response

string or null

required

ID of the currently active organization, or null if none is set or you have no memberships.

Example

curl --request GET \
  --url https://your-api.example.com/v1/workspace/active-org-id \
  --header 'Authorization: Bearer <your-session-token>'

{
  "activeOrganizationId": "org_01j9z8aabbccdd"
}

Get active organization summary

GET /v1/workspace/active-org-summary

Returns the ID and display name of the currently active organization. Convenient when you only need to show the org name in a header or breadcrumb without loading full membership data.

Request headers

string

required

Bearer token from your Clerk session.

Response

string or null

required

ID of the currently active organization, or null if none is resolved.

string or null

required

Display name of the active organization, or null if none is resolved.

Example

curl --request GET \
  --url https://your-api.example.com/v1/workspace/active-org-summary \
  --header 'Authorization: Bearer <your-session-token>'

{
  "activeOrganizationId": "org_01j9z8aabbccdd",
  "organizationName": "Acme Auto Finance"
}

Get organization bundle

GET /v1/workspace/org-bundle/:orgId

Returns the complete data bundle for a single organization: the full org record (including billing and branding), all locations ordered by sortOrder, all roles ordered by slug, and all members ordered by createdAt. Also includes your own membership and role within the org. Use this endpoint to populate organization settings screens or to inspect the full permission set for a given org before performing actions.

This endpoint returns 404 if you are not an active member of the requested organization. You cannot use it to inspect orgs you have not joined.

Path parameters

string

required

ID of the organization to retrieve.

Request headers

string

required

Bearer token from your Clerk session.

Response

The response is an OrgMember record for your own membership, with the full organization and its nested collections included.

string

required

Your membership record ID.

string

required

Your user ID.

string

required

Always "ACTIVE".

object

required

Your assigned role in this organization. Same shape as the role object in list memberships.

object

required

The full organization record.

Show organization properties

string

required

Organization ID.

string

required

Display name.

string

required

URL-safe slug.

string

required

User ID of the organization owner.

string or null

required

Custom brand name, or null.

string or null

required

Logo URL, or null.

string or null

required

Primary hex color (#RRGGBB), or null.

object or null

required

Billing account. Same shape as in list memberships.

object[]

required

All org locations, ordered by sortOrder ascending.

Show location properties

string

required

Location ID.

string

required

Parent organization ID.

string

required

Location display name. Maximum 120 characters.

string or null

required

Street address, or null.

string or null

required

City, or null.

string or null

required

State, province, or region, or null.

string or null

required

Postal code, or null.

string or null

required

ISO 3166-1 alpha-2 country code in uppercase, e.g. "US", or null.

string or null

required

Phone number, or null.

number

required

Relative display order. Locations are returned ascending by this value.

object[]

required

All roles defined for the organization, ordered by slug ascending.

Show role properties

string

required

Role ID.

string

required

Role display name. Maximum 80 characters.

string

required

URL-safe slug. Maximum 32 characters.

boolean

required

true for the system owner role.

object

required

Permission map. See the org permission model.

object[]

required

All members of the organization, ordered by createdAt ascending.

Show member properties

string

required

Membership record ID.

string

required

User ID. For pending email invites, this is "invite:<email>".

string

required

Membership status. "ACTIVE" for joined members; "INVITED" for pending invites.

string or null

required

Email address for a pending invite, or null for active members.

string

required

ISO 8601 timestamp when the membership was created.

object

required

The role assigned to this member.

Error responses

Status	Body	Cause
`404`	`{ "error": "Not found." }`	You are not an active member of the requested organization.

Get user profile

GET /v1/workspace/profile

Returns your user profile record, or null if no profile has been created yet. A profile is automatically provisioned the first time you create or join an organization, or when you call the upsertUserProfile action.

Request headers

string

required

Bearer token from your Clerk session.

Response

object or null

required

Your user profile, or null if no profile record exists.

Show profile properties

string

required

Profile record ID.

string

required

Your user ID (matches the authenticated token).

string or null

required

Preferred display name. Maximum 120 characters, or null.

string or null

required

Job title or role description. Maximum 120 characters, or null.

string or null

required

Short biography. Maximum 2000 characters, or null.

string or null

required

URL to your avatar image. Maximum 2000 characters, or null.

string or null

required

Accent color or style token for profile tile display. Maximum 32 characters, or null.

string or null

required

Public profile slug used in shareable URLs. Lowercase alphanumeric with hyphens, 2–48 characters, or null.

string or null

required

ID of the organization currently set as active for this user, or null.

string

required

ISO 8601 timestamp when the profile was created.

string

required

ISO 8601 timestamp of the most recent update.

Example

curl --request GET \
  --url https://your-api.example.com/v1/workspace/profile \
  --header 'Authorization: Bearer <your-session-token>'

{
  "profile": {
    "id": "prof_01j9z8ddeeff",
    "userId": "user_clerk_abc123",
    "displayName": "Jordan Smith",
    "title": "Compliance Officer",
    "bio": "Specializing in chattel document compliance for manufactured housing.",
    "avatarUrl": "https://cdn.example.com/avatars/jordan.jpg",
    "tileAccent": "blue",
    "publicSlug": "jordan-smith",
    "activeOrganizationId": "org_01j9z8aabbccdd",
    "createdAt": "2025-09-01T08:00:00.000Z",
    "updatedAt": "2026-03-15T10:30:00.000Z"
  }
}

GET /v1/workspace/menu-core

Returns your user profile, the full memberships array, and the active organization ID in a single request. This is the same data that powers the Safeclose navigation shell, fetched in parallel from the three underlying sources. Use this endpoint to bootstrap a client application or to hydrate server-side rendering in a single round trip.

Request headers

string

required

Bearer token from your Clerk session.

Response

object or null

required

Your user profile. Same shape as the profile field in get user profile.

object[]

required

Your organization memberships. Same shape as the array returned by list memberships.

string or null

required

The currently active organization ID. Same value as get active organization ID.

Prefer this endpoint over calling the three individual endpoints separately when your use case requires all three values at startup.

Error cases

Status	Error message	Cause
`401`	`Missing Authorization Bearer token.`	No `Authorization` header was sent.
`401`	`Invalid or expired token.`	The Bearer token is malformed or has expired.
`404`	`{ "error": "Not found." }`	Org bundle requested for an org you are not a member of.

Overview

Documents

Signing

Workspace

Query workspace memberships and user profile

List memberships

Request headers

Response

Example

Get active organization ID

Request headers

Response

Example

Get active organization summary

Request headers

Response

Example

Get organization bundle

Path parameters

Request headers

Response

Error responses

Get user profile

Request headers

Response

Example

Get menu core

Request headers

Response

Error cases

​List memberships

​Request headers

​Response

​Example

​Get active organization ID

​Request headers

​Response

​Example

​Get active organization summary

​Request headers

​Response

​Example

​Get organization bundle

​Path parameters

​Request headers

​Response

​Error responses

​Get user profile

​Request headers

​Response

​Example

​Get menu core

​Request headers

​Response

​Error cases

List memberships

Request headers

Response

Example

Get active organization ID

Request headers

Response

Example

Get active organization summary

Request headers

Response

Example

Get organization bundle

Path parameters

Request headers

Response

Error responses

Get user profile

Request headers

Response

Example

Get menu core

Request headers

Response

Error cases