Project access

Who holds which role on a project.

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 a project's roles

GET /v1/orgs/{org_id}/projects/{project_id}/grants

Who has which role on the project, 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
project_id	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "created_at": "2022-04-13T15:42:05.901Z",
            "id": "string",
            "principal_id": "string",
            "principal_type": "human",
            "project_id": "string",
            "role": "string",
            "service_account_name": "string",
            "status": {
                "placements": [
                    {
                        "id": "string",
                        "locations": [
                            "string"
                        ],
                        "observed_generation": 0,
                        "reason": "string",
                        "status": "string"
                    }
                ],
                "state": "string"
            },
            "version": 0
        }
    ],
    "next_cursor": "string"
}

422 Unprocessable Entity

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

Give a project role

POST /v1/orgs/{org_id}/projects/{project_id}/grants

Gives a member or service account a role on the project, which also gives them access in each of its locations. 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
org_id	path	string		No
project_id	path	string		No

Request body

application/json202 Accepted

{
    "principal_id": "string",
    "role": "string"
}

Responses

application/jsonapplication/json

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

422 Unprocessable Entity

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

Take a project role away

DELETE /v1/orgs/{org_id}/projects/{project_id}/grants/{grant_id}

Removes the grant and revokes the access it gave in each location, which can take up to 15 minutes to reach every location. 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.
grant_id	path	string		No
idempotency-key	header	string		Yes
if-match	header	string		Yes
org_id	path	string		No
project_id	path	string		No
security	query	boolean	False	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"
        }
    ]
}

Get a project role

GET /v1/orgs/{org_id}/projects/{project_id}/grants/{grant_id}

One person's or service account's role on the project, with its version for 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.
grant_id	path	string		No
org_id	path	string		No
project_id	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "created_at": "2022-04-13T15:42:05.901Z",
    "id": "string",
    "principal_id": "string",
    "principal_type": "human",
    "project_id": "string",
    "role": "string",
    "service_account_name": "string",
    "status": {
        "placements": [
            {
                "id": "string",
                "locations": [
                    "string"
                ],
                "observed_generation": 0,
                "reason": "string",
                "status": "string"
            }
        ],
        "state": "string"
    },
    "version": 0
}

422 Unprocessable Entity

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

Change a project role

PATCH /v1/orgs/{org_id}/projects/{project_id}/grants/{grant_id}

Changes the role of an existing project grant. Send its 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.
grant_id	path	string		No
idempotency-key	header	string		Yes
if-match	header	string		Yes
org_id	path	string		No
project_id	path	string		No

Request body

application/json200 OK

{
    "role": "string"
}

Responses

application/jsonapplication/jsonapplication/json

{
    "created_at": "2022-04-13T15:42:05.901Z",
    "id": "string",
    "principal_id": "string",
    "principal_type": "human",
    "project_id": "string",
    "role": "string",
    "service_account_name": "string",
    "status": {
        "placements": [
            {
                "id": "string",
                "locations": [
                    "string"
                ],
                "observed_generation": 0,
                "reason": "string",
                "status": "string"
            }
        ],
        "state": "string"
    },
    "version": 0
}

202 Accepted

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

422 Unprocessable Entity

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

---

Schemas

Accepted

Name	Type	Description
operation	OperationLink

Grant

Name	Type	Description
created_at	string(date-time)
id	string	The grant (grt_…).
principal_id	string	A person (usr_…) or a service account (sa_…).
principal_type	string
project_id	string
role	string
service_account_name	string	A service account's grant only: its name.
status	GrantStatus
version	integer	Its version, also its ETag.

GrantChange

Name	Type	Description
role	string

GrantCreate

Name	Type	Description
principal_id	string
role	string

GrantList

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

GrantPlacement

Name	Type	Description
id	string	The project's placement (plc_…).
locations	Array<string>
observed_generation	integer | null
reason	string | null
status	string

GrantStatus

Name	Type	Description
placements	Array<GrantPlacement>
state	string

HTTPValidationError

Name	Type	Description
detail	Array<ValidationError>

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.

ValidationError

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