Permissions

For which permission each task needs, see the permissions guide.

List permissions and profiles: GET /permission-profiles
Read a member’s permissions: GET /organizations/{orgID}/members/{userID}/permissions
Replace a member’s permissions: PUT /organizations/{orgID}/members/{userID}/permissions
List your cluster grants: GET /me/resource-grants?kind=kubernetes_cluster
Check cluster access: GET /resource-access

List permissions and profiles

GET /permission-profiles

API: Business. Permission: none. Returns the fixed catalog of organization permissions and the named profiles built from it. The catalog is the same for every organization.

Response

Field	Type	Description
`permissions[].key`	string	Permission key, for example `clusters.ssh`.
`permissions[].description`	string	What the permission allows.
`permissions[].implies`	array of strings	Keys that holding this key also grants.
`profiles[].name`	string	Profile name, for example `Engineer`.
`profiles[].description`	string	Who the profile is for.
`profiles[].permissions`	array of strings	The keys the profile grants. A profile is a preset; it is not stored on the member.

Example

andromeda call business GET /permission-profiles | jq '.profiles[] | select(.name == "Engineer")'

{
  "name": "Engineer",
  "description": "Use clusters over SSH and Kubernetes",
  "permissions": ["clusters.kubernetes", "clusters.read", "clusters.ssh", "reservations.read"]
}

Read a member’s permissions

GET /organizations/{orgID}/members/{userID}/permissions

API: Business. Permission: none to read your own. Reading another member’s needs members.manage, which owners and admins hold.

Parameters

Name	In	Type	Required	Description
`orgID`	path	string	yes	Organization ID.
`userID`	path	string	yes	The member’s user ID, `user_` + ULID. Use your own from `GET /me`.

Response

Field	Type	Description
`organization_id`	string	The organization.
`user_id`	string	The member.
`role`	string	`owner`, `admin`, or `member`.
`permissions`	array of strings	Keys granted to the member directly. For an owner or admin this is `organization.owner` or `organization.admin`, which imply every other key.

Example

andromeda call business GET "/organizations/$ORG_ID/members/$USER_ID/permissions"

{
  "organization_id": "org_01J8Z3Q4R5S6T7V8W9X0Y1Z2A3",
  "user_id": "user_01J8Z3Q4R5S6T7V8W9X0Y1Z2A4",
  "role": "member",
  "permissions": ["clusters.read", "clusters.ssh"]
}

Errors

Status	Code	When
403	`forbidden`	You asked for another member’s permissions without `members.manage`.
404	`not_found`	The organization or member does not exist, or you are not a member.

Replace a member’s permissions

PUT /organizations/{orgID}/members/{userID}/permissions

API: Business. Permission: members.manage, and every key you add. Owners and admins qualify.

This sets the member’s permissions to exactly the list you send. Keys the member held and you leave out are removed. To add one key, read the current list and send it with the new key included.

Changes to SSH and Kubernetes permissions reach the organization’s running clusters automatically. Adding or removing someone’s SSH access can restart compute nodes and end running jobs; see Access changes restart nodes.

Parameters

Name	In	Type	Required	Description
`orgID`	path	string	yes	Organization ID.
`userID`	path	string	yes	The member’s user ID. Find it with `GET /organizations/{orgID}/members`.
`Idempotency-Key`	header	string	yes	1 to 200 characters. See Retrying writes.
`Audit-Reason`	header	string	yes	1 to 500 characters, stored with the change.

Request body

Field	Type	Required	Description
`permissions`	array of strings	yes	The complete set of keys. Order and duplicates do not matter. `organization.owner` and `organization.admin` are refused; those come from the role.

Response

200 with the member’s permissions after the change, in the same shape as Read a member’s permissions.

Example

echo '{"permissions": ["clusters.kubernetes", "clusters.read", "clusters.ssh"]}' |
  andromeda call \
    --header "Idempotency-Key: $(uuidgen)" \
    --header 'Audit-Reason: Kubernetes access for the training team' \
    --data @- \
    business PUT "/organizations/$ORG_ID/members/$MEMBER_ID/permissions"

{
  "organization_id": "org_01J8Z3Q4R5S6T7V8W9X0Y1Z2A3",
  "user_id": "user_01J8Z3Q4R5S6T7V8W9X0Y1Z2A8",
  "role": "member",
  "permissions": ["clusters.kubernetes", "clusters.read", "clusters.ssh"]
}

Errors

Status	Code	When
400	`invalid_request`	A header is missing, a key is unknown, or the list contains `organization.owner` or `organization.admin`.
403	`forbidden`	You lack `members.manage`, or you are adding a key you do not hold.
404	`not_found`	The member is not in the organization.
409	`invalid_state`	The member is an owner or admin. Their permissions come from the role.
409	`idempotency_mismatch`	The `Idempotency-Key` was used before with a different body.

List your cluster grants

GET /me/resource-grants?kind=kubernetes_cluster

API: Business. Permission: none. No organization membership is needed. Returns your live resource grants, including grants on clusters in organizations you do not belong to. Organization permissions are not included. Owners and admins manage grants separately from member permissions. A grant does not make you a member of the organization or give you Slurm SSH or configuration access. See Access to a shared cluster.

Parameters

Name	In	Type	Required	Description
`kind`	query	string	no	`kubernetes_cluster` returns only cluster grants. Without it, the response can also include machine grants.

Response

Field	Type	Description
`grants`	array	Your live grants.
`grants[].id`	string	Grant ID.
`grants[].resource_kind`, `.resource_id`	string	`kubernetes_cluster` and the cluster ID, for a cluster grant.
`grants[].user_id`	string	Your user ID.
`grants[].username`	string	Your primary email address. Not your Slurm username.
`grants[].relation`	string	`kubernetes.viewer`, `kubernetes.developer`, or `kubernetes.admin`.
`grants[].scope`	string, optional	Namespace. Absent for a whole-cluster grant.
`grants[].role_id`	string, optional	A custom role that narrows `relation`.
`grants[].expires_at`	timestamp, optional	When the grant expires. Absent when it does not expire.
`grants[].granted_by`, `.granted_at`		Who granted access and when.

Example

andromeda call business GET '/me/resource-grants?kind=kubernetes_cluster' |
  jq '.grants[] | {resource_id, relation, scope, expires_at}'

Check cluster access

GET /resource-access?kind=kubernetes_cluster&id={clusterID}&gate={gate}

API: Business. Checks whether you can reach a cluster, through an organization permission or a live resource grant.

Parameters

Name	In	Type	Required	Description
`kind`	query	string	yes	`kubernetes_cluster`.
`id`	query	string	yes	Cluster ID.
`gate`	query	string	yes	`read` to see the cluster, or `kubernetes` for its kubeconfig and Kubernetes sign-in.
`scope`	query	string	no	Namespace. Without it, a `200` means you can reach some part of the cluster, not necessarily every namespace.

Response

200 with user_id, kind, id, gate, and via (organization, grant, or staff), plus grant_id and expires_at when access comes from a grant. Kubernetes still checks your role and namespace on each request, so individual kubectl commands can be refused.

Example

andromeda call business GET "/resource-access?kind=kubernetes_cluster&id=$CLUSTER_ID&gate=kubernetes"

Errors

Status	When
403	You have no access to the cluster through this gate.

Overview

Business API

Platform API

List permissions and profiles

Response

Example

Read a member’s permissions

Parameters

Response

Example

Errors

Replace a member’s permissions

Parameters

Request body

Response

Example

Errors

List your cluster grants

Parameters

Response

Example

Check cluster access

Parameters

Response

Example

Errors

​List permissions and profiles

​Response

​Example

​Read a member’s permissions

​Parameters

​Response

​Example

​Errors

​Replace a member’s permissions

​Parameters

​Request body

​Response

​Example

​Errors

​List your cluster grants

​Parameters

​Response

​Example

​Check cluster access

​Parameters

​Response

​Example

​Errors

List permissions and profiles

Response

Example

Read a member’s permissions

Parameters

Response

Example

Errors

Replace a member’s permissions

Parameters

Request body

Response

Example

Errors

List your cluster grants

Parameters

Response

Example

Check cluster access

Parameters

Response

Example

Errors