Members and invitations¶

The organization's members, their roles, and invitations.

Paths are relative to your API address. See Authentication and Operations. Changes that answer 202 Accepted return an operation to follow.

Request and response examples are generated from the schema; the tables under Schemas are the reference.

List invitations¶

GET /v1/orgs/{org_id}/invitations

The organization's invitations and their state.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`org_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "created_at": "2022-04-13T15:42:05.901Z",
            "email": "string",
            "expires_at": "2022-04-13T15:42:05.901Z",
            "id": "string",
            "issued_by": "string",
            "project_grants": [
                {
                    "project_id": "string",
                    "role": "string"
                }
            ],
            "role": "string"
        }
    ]
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Invite someone¶

POST /v1/orgs/{org_id}/invitations

Invites an e-mail address to the organization with a role and, optionally, project roles. The link is in this response only.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`org_id`	path	string		No

Request body

application/json201 Created

{
    "email": "string",
    "project_grants": [
        {
            "project_id": "string",
            "role": "string"
        }
    ],
    "role": "string"
}

Responses

application/jsonapplication/json

{
    "email": "string",
    "emailed": true,
    "expires_at": "2022-04-13T15:42:05.901Z",
    "id": "string",
    "link": "string",
    "project_grants": [
        {
            "project_id": "string",
            "role": "string"
        }
    ],
    "reissue_required": true,
    "role": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Revoke an invitation¶

DELETE /v1/orgs/{org_id}/invitations/{invitation_id}

Stops a pending invitation's link from working.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`invitation_id`	path	string		No
`org_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "id": "string",
    "state": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Send an invitation again¶

POST /v1/orgs/{org_id}/invitations/{invitation_id}:resend

Replaces a pending invitation with an identical one and a new link, returned in this response only; the old link stops working.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`invitation_id`	path	string		No
`org_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "email": "string",
    "emailed": true,
    "expires_at": "2022-04-13T15:42:05.901Z",
    "id": "string",
    "link": "string",
    "reissue_required": true,
    "replaced_id": "string",
    "role": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

List members' project roles¶

GET /v1/orgs/{org_id}/member-grants

Each member's project roles, in the same order and pages as the member list. Only projects the caller may see are included; visibility says whether the answer is complete.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`cursor`	query	string		Yes
`limit`	query	integer		Yes
`member`	query	string		Yes
`org_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "grants": [
                {
                    "created_at": "2022-04-13T15:42:05.901Z",
                    "id": "string",
                    "project_id": "string",
                    "role": "string",
                    "version": 0
                }
            ],
            "member_id": "string",
            "principal_id": "string"
        }
    ],
    "next_cursor": "string",
    "visibility": "organization"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

List members¶

GET /v1/orgs/{org_id}/members

The organization's members with their roles and status, a page at a time.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`cursor`	query	string		Yes
`limit`	query	integer		Yes
`org_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "account_status": "string",
            "display_name": "string",
            "email": "string",
            "id": "string",
            "principal_id": "string",
            "roles": [
                "string"
            ],
            "status": "string",
            "version": 0
        }
    ],
    "next_cursor": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Leave the organization¶

POST /v1/orgs/{org_id}/members/me:leave

Removes the caller from this organization, as removing a member does. The organization's only owner is refused until they make someone else an owner.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`org_id`	path	string		No

Responses

202 Accepted

application/jsonapplication/json

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Remove a member¶

DELETE /v1/orgs/{org_id}/members/{member_id}

Removes the person from the organization, with their project roles, invitations they issued and personal SSH keys; their access in each location is revoked. Accepted at once: follow the returned operation until it finishes.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`if-match`	header	string		Yes
`member_id`	path	string		No
`org_id`	path	string		No

Responses

202 Accepted

application/jsonapplication/json

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Change a member's roles¶

PATCH /v1/orgs/{org_id}/members/{member_id}

Sets the member's organization roles. Send the member's current version in If-Match.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`if-match`	header	string		Yes
`member_id`	path	string		No
`org_id`	path	string		No

Request body

application/json200 OK

{
    "roles": [
        "string"
    ]
}

Responses

application/jsonapplication/json

{
    "id": "string",
    "roles": [
        "string"
    ],
    "version": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Resume a member¶

POST /v1/orgs/{org_id}/members/{member_id}:resume

Gives a suspended member their access back. Accepted at once: follow the returned operation until it finishes.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`if-match`	header	string		Yes
`member_id`	path	string		No
`org_id`	path	string		No

Responses

202 Accepted

application/jsonapplication/json

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Suspend a member¶

POST /v1/orgs/{org_id}/members/{member_id}:suspend

Stops the member using the organization and its projects until resumed, including in each location's console and CLI. Accepted at once: follow the returned operation until it finishes.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`if-match`	header	string		Yes
`member_id`	path	string		No
`org_id`	path	string		No

Responses

202 Accepted

application/jsonapplication/json

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Make another member an owner¶

POST /v1/orgs/{org_id}/ownership:transfer

Makes another active member an owner and, unless asked to stay an owner, makes the caller an admin or member, in one step. Needs a recent second-factor sign-in.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`org_id`	path	string		No

Request body

application/json200 OK

{
    "member_id": "string",
    "then": "owner"
}

Responses

application/jsonapplication/json

{
    "members": [
        {
            "id": "string",
            "roles": [
                "string"
            ]
        }
    ]
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Schemas¶

Accepted¶

Name	Type	Description
`operation`	OperationLink

HeldProjectRole¶

Name	Type	Description
`created_at`	string(date-time)
`id`	string	The grant (`grt_…`).
`project_id`	string
`role`	string
`version`	integer

HTTPValidationError¶

Name	Type	Description
`detail`	Array<ValidationError>

InvitationList¶

Name	Type	Description
`items`	Array<PendingInvitation>

InvitationRevoked¶

Name	Type	Description
`id`	string
`state`	string

InviteBody¶

Name	Type	Description
`email`	string
`project_grants`	Array<InviteGrant>
`role`	string

InvitedProjectRole¶

Name	Type	Description
`project_id`	string	The project (`prj_…`).
`role`	string	`project_admin`, `project_member` or `project_reader`.

InviteGrant¶

Name	Type	Description
`project_id`	string
`role`	string

IssuedInvitation¶

Name	Type	Description
`email`	string
`emailed`	boolean	Whether NubeStack Cloud also e-mailed the link.
`expires_at`	string(date-time)
`id`	string	The invitation (`inv_…`).
`link`	string \| null	The invitation link, with its secret. In this response only: null when the same `Idempotency-Key` replays it.
`project_grants`	Array<InvitedProjectRole>
`reissue_required`	boolean	Only on a replay, and then true: the link cannot be shown again; send the invitation again for a new one.
`role`	string	The organization role it offers.

Member¶

Name	Type	Description
`account_status`	string	To owners and admins only: the person's NubeStack Cloud account, which can be disabled while the membership is active.
`display_name`	string \| null
`email`	string \| null	To owners and admins only.
`id`	string	The membership (`mem_…`), with its version for `If-Match`.
`principal_id`	string	The person (`usr_…`).
`roles`	Array<string>
`status`	string	`active` or `suspended`.
`version`	integer

MemberGrantList¶

Name	Type	Description
`items`	Array<MemberProjectRoles>
`next_cursor`	string \| null	Pass as `cursor` for the next page; null on the last page.
`visibility`	string	`organization`: every project; `granted_projects`: only the projects the caller holds a role on.

MemberList¶

Name	Type	Description
`items`	Array<Member>
`next_cursor`	string \| null	Pass as `cursor` for the next page; null on the last page.

MemberProjectRoles¶

Name	Type	Description
`grants`	Array<HeldProjectRole>
`member_id`	string
`principal_id`	string

MemberRoleChange¶

Name	Type	Description
`id`	string	The membership (`mem_…`).
`roles`	Array<string>

MemberRoles¶

Name	Type	Description
`id`	string	The membership (`mem_…`).
`roles`	Array<string>
`version`	integer	The membership's new version, also its `ETag`.

OperationLink¶

Name	Type	Description
`href`	string	Where to read the operation; also the `Location` header.
`id`	string	The operation's ID (`op_…`).
`state`	string \| null	Its state when accepted, normally `queued`.

OwnershipTransferred¶

Name	Type	Description
`members`	Array<MemberRoleChange>

PendingInvitation¶

Name	Type	Description
`created_at`	string(date-time)
`email`	string
`expires_at`	string(date-time)
`id`	string
`issued_by`	string \| null	The member who sent it (`usr_…`); null otherwise.
`project_grants`	Array<InvitedProjectRole>
`role`	string

ResentInvitation¶

Name	Type	Description
`email`	string
`emailed`	boolean	Whether NubeStack Cloud also e-mailed the link.
`expires_at`	string(date-time)
`id`	string	The new invitation (`inv_…`).
`link`	string \| null	The invitation link, with its secret. In this response only: null when the same `Idempotency-Key` replays it.
`reissue_required`	boolean	Only on a replay, and then true: the link cannot be shown again; send the invitation again for a new one.
`replaced_id`	string	The invitation it replaces, whose link stopped working.
`role`	string

RolesBody¶

Name	Type	Description
`roles`	Array<string>

TransferBody¶

Name	Type	Description
`member_id`	string
`then`	string

ValidationError¶

Name	Type	Description
`ctx`
`input`
`loc`	Array<>
`msg`	string
`type`	string