Portal: resources, groups, tags and dashboards

What Cloud's portal is built on. Resources are addressed by kind and reference: project (a Serverless App Service, by its id), database and bucket (by resource id), domain (by hostname), repository (by resource id) and agent (by device id). Favourites, recent resources and dashboards are per person; people only, not keys.

GET /v1/orgs/:orgId/portal/resources

Every resource of the org you may read, of every kind (Serverless App Services, databases, buckets, domains, repositories, agents), with its resource group and tags. q keeps those with every word in their name, details, id or tags; kind, group (a resource group id, or none) and tag (key or key=value) filter; limit caps the list (default 500). total and counts (by kind) are of every resource you may read, before filters.

Auth: user access token or platform agent key

Response 200

{
  resources: {
    kind: "project" | "repository" | "agent" | "database" | "bucket" | "domain"
    id: string
    name: string
    detail?: string
    location?: string
    region?: string
    projectId?: string
    groupId?: string
    tags: {
      key: string
      value: string
    }[]
    status?: string
    createdAt?: number
    updatedAt?: number
  }[]
  total: number
  counts: {
    project?: number
    repository?: number
    agent?: number
    database?: number
    bucket?: number
    domain?: number
  }
}

GET /v1/orgs/:orgId/portal/resources/:kind/:ref

One resource with its resource group and tags.

Auth: user access token or platform agent key · Scopes: projects:read (for a Serverless App Service (project)), resources:read (for a database or bucket), domains:read (for a domain), git:read (for a repository), agents:read (for an agent)

Response 200

{
  resource: {
    kind: "project" | "repository" | "agent" | "database" | "bucket" | "domain"
    id: string
    name: string
    detail?: string
    location?: string
    region?: string
    projectId?: string
    groupId?: string
    tags: {
      key: string
      value: string
    }[]
    status?: string
    createdAt?: number
    updatedAt?: number
  }
}

Errors

PUT /v1/orgs/:orgId/portal/resources/:kind/:ref

Sets a resource's resource group (groupId, or null for none) and its tags (tags: up to 20 { key, value }, keys unique; replaces them all). Needs the right to change that resource.

Auth: user access token or platform agent key · Scopes: projects:read (for a Serverless App Service (project)), resources:read (for a database or bucket), domains:read (for a domain), git:read (for a repository), agents:read (for an agent), projects:write (for a Serverless App Service (project)), resources:write (for a database or bucket), domains:write (for a domain), git:write (for a repository)

Request body

Response 200

{
  groupId: null | string
  tags: {
    key: string
    value: string
  }[]
}

Errors

GET /v1/orgs/:orgId/portal/resources/:kind/:ref/activity

What happened to a resource, newest first: its entries in the org's audit log, filtered like the log (action, actor) and paged (cursor, limit). Readable by those who may read the resource.

Auth: user access token or platform agent key · Scopes: projects:read (for a Serverless App Service (project)), resources:read (for a database or bucket), domains:read (for a domain), git:read (for a repository), agents:read (for an agent)

Response 200

{
  events: {
    eventId: string
    orgId: string
    action: string
    actor: {
      type: "user" | "key" | "device" | "system"
      id: string
      label?: string
    }
    target: {
      type: string
      id: string
      label?: string
    }
    metadata?: {
      [key: string]: unknown
    }
    ip?: string
    userAgent?: string
    createdAt: number
  }[]
  cursor: null | string
  retentionDays?: number
}

Errors

GET /v1/orgs/:orgId/portal/resources/:kind/:ref/access

Who can reach a resource: each member, their role and what that role lets them do with it (manage, change or read), and the groups whose grants widen access to a Serverless App Service or a repository. Roles are changed in Tenant.

Auth: user access token or platform agent key · Scopes: members:read, projects:read (for a Serverless App Service (project)), resources:read (for a database or bucket), domains:read (for a domain), git:read (for a repository), agents:read (for an agent)

Response 200

{
  members: {
    userId: string
    name?: string
    email?: string
    role: "owner" | "admin" | "developer" | "viewer"
    access: string
  }[]
  groups: {
    teamId: string
    name: string
    access: string
  }[]
}

Errors

GET /v1/orgs/:orgId/portal/groups

The org's resource groups.

Auth: user access token or platform agent key · Scope: org:read

Response 200

{
  groups: {
    groupId: string
    name: string
    description?: string
    createdAt?: number
  }[]
}

POST /v1/orgs/:orgId/portal/groups

Creates a resource group (name, optional description). Needs resources:write.

Auth: user access token or platform agent key · Scope: resources:write

Request body

Response 201

{
  group: {
    groupId: string
    name: string
    description?: string
    createdAt?: number
  }
}

Errors

PATCH /v1/orgs/:orgId/portal/groups/:resourceGroupId

Renames a resource group or changes its description. Needs resources:write.

Auth: user access token or platform agent key · Scope: resources:write

Request body

Response 200

{
  group: {
    groupId: string
    name: string
    description?: string
  }
}

Errors

DELETE /v1/orgs/:orgId/portal/groups/:resourceGroupId

Deletes a resource group; its resources stay, outside any group. Needs resources:write.

Auth: user access token or platform agent key · Scope: resources:write

Response 200

{
  ok: true
}

Errors

GET /v1/orgs/:orgId/portal/me

Your portal in this org: favourite services in order (null: the defaults), recent resources and the dashboard Dashboard opens. People only.

Auth: user access token or platform agent key · Scope: org:read

Response 200

{
  favourites: null | string[]
  recent: {
    kind: "project" | "repository" | "agent" | "database" | "bucket" | "domain"
    id: string
    name: string
    at: number
  }[]
  dashboardId: null | string
}

Errors

PUT /v1/orgs/:orgId/portal/me

Saves your favourite services (favourites: service keys in order, null for the defaults) or the dashboard Dashboard opens (dashboardId).

Auth: user access token or platform agent key · Scope: org:read

Request body

Response 200

{
  favourites: null | string[]
  recent: {
    kind: "project" | "repository" | "agent" | "database" | "bucket" | "domain"
    id: string
    name: string
    at: number
  }[]
  dashboardId: null | string
}

Errors

POST /v1/orgs/:orgId/portal/me/recent

Records that you opened a resource (kind, ref), for Recent.

Auth: user access token or platform agent key · Scopes: projects:read (for a Serverless App Service (project)), resources:read (for a database or bucket), domains:read (for a domain), git:read (for a repository), agents:read (for an agent)

Request body

Response 200

{
  recent: {
    kind: "project" | "repository" | "agent" | "database" | "bucket" | "domain"
    id: string
    name: string
    at: number
  }[]
}

Errors

GET /v1/orgs/:orgId/portal/dashboards

Dashboards you can open: yours and those shared with the organization (without their tiles).

Auth: user access token or platform agent key · Scope: org:read

Response 200

{
  dashboards: {
    tiles?: {
      id: string
      type: "resource" | "link" | "recent" | "note" | "deployments" | "traffic" | "services"
      x: number
      y: number
      w: number
      h: number
      config: {
        [key: string]: string
      }
    }[]
    dashboardId: string
    name: string
    ownerId: string
    shared: boolean
    updatedAt?: number
  }[]
}

Errors

POST /v1/orgs/:orgId/portal/dashboards

Creates a dashboard (name, optional shared and tiles); yours alone unless shared.

Auth: user access token or platform agent key · Scope: org:read

Request body

Response 201

{
  dashboard: {
    tiles?: {
      id: string
      type: "resource" | "link" | "recent" | "note" | "deployments" | "traffic" | "services"
      x: number
      y: number
      w: number
      h: number
      config: {
        [key: string]: string
      }
    }[]
    dashboardId: string
    name: string
    ownerId: string
    shared: boolean
    updatedAt?: number
  }
}

Errors

GET /v1/orgs/:orgId/portal/dashboards/:dashboardId

A dashboard with its tiles.

Auth: user access token or platform agent key

Response 200

{
  dashboard: {
    canChange?: boolean
    tiles?: {
      id: string
      type: "resource" | "link" | "recent" | "note" | "deployments" | "traffic" | "services"
      x: number
      y: number
      w: number
      h: number
      config: {
        [key: string]: string
      }
    }[]
    dashboardId: string
    name: string
    ownerId: string
    shared: boolean
    updatedAt?: number
  }
}

Errors

PUT /v1/orgs/:orgId/portal/dashboards/:dashboardId

Changes a dashboard: name, shared (owners only) and tiles (replaced; positions are compacted).

Auth: user access token or platform agent key

Request body

Response 200

{
  dashboard: {
    canChange: true
    tiles?: {
      id: string
      type: "resource" | "link" | "recent" | "note" | "deployments" | "traffic" | "services"
      x: number
      y: number
      w: number
      h: number
      config: {
        [key: string]: string
      }
    }[]
    dashboardId: string
    name: string
    ownerId: string
    shared: boolean
    updatedAt?: number
  }
}

Errors

DELETE /v1/orgs/:orgId/portal/dashboards/:dashboardId

Deletes a dashboard (its owner, or for a shared one those who manage the organization).

Auth: user access token or platform agent key

Response 200

{
  ok: true
}

Errors