Organizations

An organization is the tenant that owns projects, devices, members, and tokens. Organization endpoints read its profile and plan status, and let an Owner update the profile.

Method	Endpoint	Description
GET	/api/v2/organizations/	List organizations of the signed-in user
GET	/api/v2/organizations/{slug}/	Retrieve an organization
GET	/api/v2/organizations/{slug}/membership/	Retrieve membership status
PATCH	/api/v2/organizations/{slug}/	Update an organization

Creating, deleting, and leaving an organization happen in the console and need a signed-in user.

The organization object

{
  "name": "YenGear Lab",
  "slug": "yengear",
  "logo": "https://dl.yengear.com/media/org/logo.png",
  "allow_join": false,
  "allow_search": false,
  "is_active": true,
  "access_config": null
}

Field	Type	Description
name	string	Display name
slug	string	Organization identifier. Set at creation and read-only afterwards.
logo	string | null	Logo URL
allow_join	boolean	Whether users can request to join
allow_search	boolean	Whether the organization appears in search
is_active	boolean	API tokens of an inactive organization are rejected
access_config	object | null	Role and project scope of the signed-in user: role, role_display, all_projects, projects. null for API tokens.

List organizations

GET /api/v2/organizations/

Returns every organization the signed-in user belongs to.

Authentication

User JWT only. API tokens receive 403.

Example request

curl 'https://dl.yengear.com/api/v2/organizations/' \
  -H 'Authorization: Bearer YOUR_USER_JWT'

Example response

{
  "success": true,
  "data": [
    { "name": "YenGear Lab", "slug": "yengear", "logo": null, "allow_join": false, "allow_search": false, "is_active": true, "access_config": { "role": "owner", "role_display": "Owner", "all_projects": true, "projects": [] } }
  ],
  "error": null
}

Responses

• 200: Array of organization objects.
• 403: Missing credentials, or the request used an API token.

Retrieve an organization

GET /api/v2/organizations/{slug}/

Returns one organization. With an API token, the response is always the token's own organization.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
slug	string	Yes	Organization slug

Example request

curl 'https://dl.yengear.com/api/v2/organizations/yengear/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Example response

{
  "success": true,
  "data": {
    "name": "YenGear Lab",
    "slug": "yengear",
    "logo": null,
    "allow_join": false,
    "allow_search": false,
    "is_active": true,
    "access_config": null
  },
  "error": null
}

Responses

• 200: The organization object.
• 403: Authentication failed, or the user is not a member.

Retrieve membership status

GET /api/v2/organizations/{slug}/membership/

Returns the organization's plan status. Read-only and Operator callers receive a summary; Manager and Owner callers receive the full status, including plan details, entitlements, and usage.

Authentication

Bearer token. Minimum role: Read-only.

Path parameters

Name	Type	Required	Description
slug	string	Yes	Organization slug

Example request

curl 'https://dl.yengear.com/api/v2/organizations/yengear/membership/' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Example response

Summary for Read-only and Operator callers:

{
  "success": true,
  "data": {
    "organization": "yengear",
    "plan_name": "Pro",
    "status": "active",
    "is_active": true,
    "is_readonly": false,
    "can_write": true,
    "reason": null
  },
  "error": null
}

When can_write is false, reason is membership_readonly and write endpoints fail with the same reason. See Plan errors.

Responses

• 200: Membership status.
• 403: Authentication failed.

Update an organization

PATCH /api/v2/organizations/{slug}/

Updates the organization profile. PUT behaves the same as PATCH: send only the fields to change.

Authentication

User JWT with X-Organization-Slug. Minimum role: Owner (user). API tokens receive 403.

Path parameters

Name	Type	Required	Description
slug	string	Yes	Organization slug

Request body

Name	Type	Required	Description
name	string	No	Display name
logo	file | string	No	Multipart file, base64 string, or data:image/...;base64, URI. JPG, PNG, GIF, or WebP, up to 5 MB.
logoData	string	No	Base64 logo, as an alternative to logo
allow_join	boolean	No	Allow join requests
allow_search	boolean	No	Show the organization in search

slug and is_active are read-only.

Example request

curl -X PATCH 'https://dl.yengear.com/api/v2/organizations/yengear/' \
  -H 'Authorization: Bearer YOUR_USER_JWT' \
  -H 'X-Organization-Slug: yengear' \
  -H 'Content-Type: application/json' \
  -d '{"name": "YenGear Smart Agriculture", "allow_join": true}'

Responses

• 200: The updated organization object.
• 400: Invalid field, or a logo that is not a supported image or exceeds 5 MB.
• 403: The caller is not an Owner, the request used an API token, or the plan is read-only (membership_readonly).

Related

• Tokens
• Organizations in the console