Cosmoner Docs
API Reference

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.

GET
/v1/projects/{projectId}/members

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.

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Response 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"  }}
POST
/v1/projects/{projectId}/members/biller/decline

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.

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Response 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"  }}
POST
/v1/projects/{projectId}/members/biller/transfer

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.

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Request 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"  }}
DELETE
/v1/projects/{projectId}/members/invitations/{invitationId}

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.

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length
invitationId*string
Length1 <= length

Response 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"  }}
GET
/v1/projects/{projectId}/members/me

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.

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Response 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"  }}

On this page