Members
The people in a project, each holding one role: `viewer`, `developer`, `admin` or `owner`. Viewers are read-only across the API. Developers create, change, deploy and delete the project's resources, billable ones included, but cannot change its members, plans, API keys, secrets, variables or settings. Admins can do everything except delete the project, which is the owner's alone. The payment method, refunds and service agreements are the biller's, whatever their role. Only an owner can grant the owner role, change an owner's role or remove an owner. [Team roles](/docs/guides/team-roles) lists exactly what each role may do; a request the caller's role does not allow is refused with `403 INSUFFICIENT_ROLE`. Exactly one member is the **biller**, responsible for paying for the project. The biller cannot be removed, or leave, while they hold that responsibility — the attempt is refused with `409 BILLER_CANNOT_LEAVE` — so transfer it to another member first. Inviting, removing and changing the role of a member are done from the control panel by a signed-in owner or admin, never with an API key: a key is refused with `401 API_KEY_NOT_ALLOWED`. A pending invitation can be cancelled through the API.
Every member of the project in the order they joined, the invitations still waiting for an answer, and who holds billing responsibility — including a transfer that is waiting to be accepted.
Auth: a project API key carrying members:read.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= lengthResponse Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/projects/string/members"{ "success": true, "data": { "orgId": "string", "currentUserId": "string", "billerUserId": "string", "pendingBillerUserId": "string", "members": [ { "id": "string", "organizationId": "string", "userId": "string", "role": "viewer", "createdAt": "2019-08-24T14:15:22Z", "user": { "name": "string", "email": "user@example.com", "image": "string" } } ], "pendingInvitations": [ { "id": "string", "email": "user@example.com", "role": "viewer", "expiresAt": "2019-08-24T14:15:22Z" } ] }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}Clears the pending billing transfer. The nominee calls this to decline it, and the current
biller to withdraw it; each notifies the other. Anyone else is refused with
403 BILLER_ONLY. For an API key, the caller is the member who created the key, so the key has to belong to the right person.
Auth: a project API key carrying all of members:read and members:write.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= lengthResponse Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/projects/string/members/biller/decline"{ "success": true, "data": null}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}Nominates another member, by their userId, to take over paying for the project. Only the
current biller can start a transfer; anyone else is refused with 403 BILLER_ONLY. For an API key, the caller is the member who created the key, so the key has to belong to the right person.
Nothing changes until the nominee accepts. They are notified by email and in the control panel, and accept there by adding a card, which becomes the project's payment method; the previous biller's card is then removed from the project. Accepting or declining notifies the outgoing biller. Nominating someone while a transfer is pending replaces that nomination.
Before transferring, the outgoing biller can have any remaining project credit refunded to their payment method from the project's billing page in the control panel; otherwise the credit stays with the project for the incoming biller. Payment-processing fees cannot be recovered, so the amount refunded is less than the credit balance.
Any role may hold billing responsibility, so a viewer who is the biller can transfer it too.
Auth: a project API key carrying all of members:read and members:write.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= lengthRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/projects/string/members/biller/transfer" \ -H "Content-Type: application/json" \ -d '{ "targetUserId": "string" }'{ "success": true, "data": null}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}Withdraws an invitation that has not been answered yet, so its link stops working. The ids of pending invitations are in List members.
Only owners and admins can cancel an invitation, as only they can send one. Inviting, removing and changing the role of a member are done from the control panel; API keys cannot change who is in a project.
Auth: a project API key carrying all of members:read and members:write.
Role: the caller must be an owner or admin of the project.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= length1 <= lengthResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/v1/projects/string/members/invitations/string"{ "success": true, "data": null}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}The caller's own role in the project. For an API key, that is the role of the member who created it.
Auth: a project API key carrying members:read.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= lengthResponse Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/projects/string/members/me"{ "success": true, "data": { "role": "viewer" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}{ "success": false, "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "issues": null, "docsUrl": "http://example.com" }}Resource groups
Named boxes drawn around resources on the project overview's resource graph. Groups nest, a resource sits in at most one, and they change only how the project is drawn — nothing a group holds behaves any differently for being in it.
Audit log
The record of who changed what in a project. Every change made through this API, the control panel or the CLI is written down with who made it, how they were authenticated, where the request came from and what it was aimed at. Events are kept for 180 days and cannot be edited or deleted. Reading the log needs the `admin` role. The [Audit log guide](/docs/guides/audit-log) says what is recorded and what is not.