User API

The user APIs are designed to handle user management.

Available URLs

URL Description
GET /api/v1/organizations/{organizationId}/groups Returns an array of groups.

Organizations

GET /organizations/{organizationId}/groups

Gets an array of groups that belong to a specific organization. The query parameter expand set to roles will return roles associated with the group.

Request
Request Headers
Name Description
Content-Type Must be application/json
Authorization The API token supplied by OnTask
URL parameters
Parameter Description
expand Optional query string parameter which can be set to roles. When this property is set, the roles object property defining user permission levels within the group will be returned in the response.

Successful Response

Response Body

An array of JSON objects with the following properties or an empty array if no instances were found.

  • tenantId (String) Unique identifier for the group.
  • tenantDisplayName (String) Name of the group.
  • tenantSlug (String) Unique, URL-safe identifier for the group.
  • ownerUserId (String) Unique identifier for the owning user.
  • type (String) Type of tenant.
  • parentTenantId (String) Tenant Id of the owning organization.
  • status (String) The groups status.
  • tenantLogoUrl (String) URL for the tenants company logo.
  • tenantLogoFGColor (String) The company tenants logo foreground color.
  • tenantBGColor (String) The company tenants logo background color.
  • tenantLogoText (String) The company tenants logo text.
  • tenantLogoLink (String) The company tenants logo link.
  • memberCount (Integer) Indicates the number of members inside the group.
  • roles (Object Array) An array of JSON objects with the following properties which define the role:
    • roleId (String) Unique identifier of the role.
    • tenantId (String) Unique identifier of the tenant the role belongs to.
    • roleDisplayName (String) The display value for the role.
    • isDefault (Numeric) Indicates if the role will be applied by default to users added to the group.

Error Responses

Status Code JSON errorCode Description
401 Unauthorized Insufficient permissions
404 ResourceNotFound The specified organization does not exist
480 InvalidInput An invalid parameter was provided
480 InvalidToken An invalid Authorization header token was provided

Example

Request

GET /organizations/7713104a-71f4-46a5-9154-f5d3fe8097ae/groups
Content-Type: application/json
Authorization: Bearer eyJhbGciOiOPXzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI5ZWY0Yjk3OS05YTQzLAQzMWYtYmZjOC05MjhjOTlhMGRiMzkiLCJpYXQiOjE0OTI1NDk4NzQsImV4cCI6MTQ5MjcyMjY3NCwiaXNzIjoiaHR0cHM6Ly9kZXYub250YXNrLmlvIn0.hGJuW0QbOYrXSq98cxCSoBL_DkMT-ITDT4H59d9tgtq

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "tenantId": "078zplcb-6367-4f79-ba52-d7f4f7ffaad2",
    "tenantDisplayName": "Sales Group",
    "tenantSlug": null,
    "ownerUserId": "9ef4b109-9a43-432f-bfc8-928c99a0db39",
    "type": "group",
    "parentTenantId": "7713104a-71f4-46a5-9154-f5d3fe8097ae",
    "status": "active",
    "tenantLogoUrl": null,
    "tenantLogoFGColor": null,
    "tenantLogoBGColor": null,
    "tenantLogoText": null,
    "tenantLogoLink": null,
    "memberCount": 10
  }
]