Account API

The account API allows users to query and manipulate their own account data.

Create a new account. The response is the created account data.

Path	Method	Protected
`/v1/accounts`	POST	Yes

Example Request JSON


{
  "name": "string",
  "email": "string",
  "roles": [
    "admin"
  ]
}

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "revision": 0,
  "name": "string",
  "email": "string",
  "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",
  "roles": [
    "admin"
  ],
  "accountRootCardId": "dc9e74a3-7f70-412c-9cf0-c0704225960b"
}

Retrieve an account for a given Account ID

Path	Method	Protected
`/v1/accounts/{account_id}`	GET	Yes

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "revision": 0,
  "name": "string",
  "email": "string",
  "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",
  "roles": [
    "admin"
  ],
  "accountRootCardId": "dc9e74a3-7f70-412c-9cf0-c0704225960b"
}

Delete an account.

Path	Method	Protected
`/v1/accounts/{account_id}`	DELETE	Yes

Query Parameters

Name	Type	Required	Description
current_revision	integer	Yes	-

Example Response JSON

{}

Update account

Path	Method	Protected
`/v1/accounts/{account_id}`	PATCH	Yes

Allows the user to change mutable account details such as name.

The account email is immutable after account creation.

Changing the planId is not allowed and the request will be rejected. The response is the updated account data.

Example Request JSON


{
  "currentRevision": 0,
  "name": "string"
}

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "revision": 0,
  "name": "string",
  "email": "string",
  "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",
  "roles": [
    "admin"
  ],
  "accountRootCardId": "dc9e74a3-7f70-412c-9cf0-c0704225960b"
}

Retrieve an account by email address.

Path	Method	Protected
`/v1/accounts/by-email/{account_email}`	GET	Yes

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "revision": 0,
  "name": "string",
  "email": "string",
  "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",
  "roles": [
    "admin"
  ],
  "accountRootCardId": "dc9e74a3-7f70-412c-9cf0-c0704225960b"
}

Get an account’s plan

Path	Method	Protected
`/v1/accounts/{account_id}/plan`	GET	Yes

Example Response JSON


{
  "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",
  "name": "string",
  "appLimit": 0,
  "envLimit": 0,
  "componentLimit": 0,
  "workerConnectionLimit": 0,
  "storageLimit": 0,
  "blobStorageLimit": 0,
  "monthlyGasLimit": 0,
  "monthlyUploadLimit": 0,
  "maxMemoryPerWorker": 0,
  "maxMemoryPerWorkerCeiling": 0,
  "maxMemoryPerWorkerUserConfigurable": true,
  "monthlyMemoryGbSeconds": 0,
  "monthlyMemoryGbSecondsCeiling": 0,
  "monthlyMemoryGbSecondsUserConfigurable": true,
  "maxTableElementsPerWorker": 0,
  "maxDiskSpacePerWorker": 0,
  "maxDiskSpacePerWorkerCeiling": 0,
  "maxDiskSpacePerWorkerUserConfigurable": true,
  "perInvocationHttpCallLimit": 0,
  "perInvocationRpcCallLimit": 0,
  "monthlyHttpCallLimit": 0,
  "monthlyRpcCallLimit": 0,
  "maxConcurrentAgentsPerExecutor": 0,
  "oplogWritesPerSecond": 0
}

Set the plan of an account

Path	Method	Protected
`/v1/accounts/{account_id}/plan`	PUT	Yes

Example Request JSON


{
  "currentRevision": 0,
  "plan": "c685f150-7cb7-436f-9700-386be171480b"
}

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "revision": 0,
  "name": "string",
  "email": "string",
  "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",
  "roles": [
    "admin"
  ],
  "accountRootCardId": "dc9e74a3-7f70-412c-9cf0-c0704225960b"
}

List all tokens of an account.

The format of each element is the same as the data object in the oauth2 endpoint’s response.

Path	Method	Protected
`/v1/accounts/{account_id}/tokens`	GET	Yes

Example Response JSON


{
  "values": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
      "createdAt": "2019-08-24T14:15:22Z",
      "expiresAt": "2019-08-24T14:15:22Z"
    }
  ]
}

Create new token

Path	Method	Protected
`/v1/accounts/{account_id}/tokens`	POST	Yes

Creates a new token with a given expiration date. The response not only contains the token data but also the secret which can be passed as a bearer token to the Authorization header to the Golem Cloud REST API.

Example Request JSON


{
  "expiresAt": "2019-08-24T14:15:22Z"
}

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "secret": "stringstringstri",
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "createdAt": "2019-08-24T14:15:22Z",
  "expiresAt": "2019-08-24T14:15:22Z"
}

Get account usage for a UTC calendar month.

Path	Method	Protected
`/v1/accounts/{account_id}/usage`	GET	Yes

Compute is reported in GCU, memory in allocated linear-memory GB-seconds, and durable and ephemeral storage in GB-month using byte-seconds / (1024^3 * 730 * 3600). asOf is when the registry last received a usage snapshot for the period, or the response time if no snapshot exists. Metering status distinguishes enabled meters that measured zero from disabled meters. unknown means no usage producer has reported metering state for the period. Durable and ephemeral storage both reflect the shared filesystem meter.

Query Parameters

Name	Type	Required	Description
period	string	No	Billing period in YYYY-MM format. Defaults to the current UTC calendar month.

Example Response JSON


{
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "usage": {
    "period": {
      "year": 0,
      "month": 1
    },
    "asOf": "2019-08-24T14:15:22Z",
    "computeGcu": 0.1,
    "memoryGbSeconds": 0,
    "durableStorageGbMonth": 0.1,
    "ephemeralStorageGbMonth": 0.1,
    "metering": {
      "compute": "enabled",
      "memory": "enabled",
      "durableStorage": "enabled",
      "ephemeralStorage": "enabled"
    }
  }
}

Get sparse account usage for closed UTC calendar months, newest first.

Path	Method	Protected
`/v1/accounts/{account_id}/usage/history`	GET	Yes

Each item uses the same metrics and metering-status contract as current usage. The response does not include plan or limit metadata because historical limits are not snapshotted.

Query Parameters

Name	Type	Required	Description
last	integer	No	-

Example Response JSON


[
  {
    "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
    "usage": {
      "period": {
        "year": 0,
        "month": 1
      },
      "asOf": "2019-08-24T14:15:22Z",
      "computeGcu": 0.1,
      "memoryGbSeconds": 0,
      "durableStorageGbMonth": 0.1,
      "ephemeralStorageGbMonth": 0.1,
      "metering": {
        "compute": "enabled",
        "memory": "enabled",
        "durableStorage": "enabled",
        "ephemeralStorage": "enabled"
      }
    }
  }
]

Get effective storage-per-agent override metadata for an account.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/max-storage-per-agent`	GET	Yes

Example Response JSON


{
  "effectiveValue": 0,
  "planDefault": 0,
  "overrideValue": 0,
  "ceiling": 0,
  "userConfigurable": true
}

Set a storage-per-agent override for an account. Setting an expiry requires an admin token.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/max-storage-per-agent`	PUT	Yes

Example Request JSON


{
  "value": 0,
  "expiresAt": "2019-08-24T14:15:22Z"
}

Example Response JSON


{
  "effectiveValue": 0,
  "planDefault": 0,
  "overrideValue": 0,
  "ceiling": 0,
  "userConfigurable": true
}

Clear a storage-per-agent override for an account.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/max-storage-per-agent`	DELETE	Yes

Example Response JSON


{
  "effectiveValue": 0,
  "planDefault": 0,
  "overrideValue": 0,
  "ceiling": 0,
  "userConfigurable": true
}

Get the effective maximum linear memory per agent.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/max-memory-per-agent`	GET	Yes

Example Response JSON


{
  "effectiveValue": 0,
  "planDefault": 0,
  "overrideValue": 0,
  "ceiling": 0,
  "userConfigurable": true
}

Set the maximum linear memory per agent. Setting an expiry requires an admin token.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/max-memory-per-agent`	PUT	Yes

Example Request JSON


{
  "value": 0,
  "expiresAt": "2019-08-24T14:15:22Z"
}

Example Response JSON


{
  "effectiveValue": 0,
  "planDefault": 0,
  "overrideValue": 0,
  "ceiling": 0,
  "userConfigurable": true
}

Clear the maximum linear memory per-agent override.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/max-memory-per-agent`	DELETE	Yes

Example Response JSON


{
  "effectiveValue": 0,
  "planDefault": 0,
  "overrideValue": 0,
  "ceiling": 0,
  "userConfigurable": true
}

Get the effective monthly memory GB-seconds allowance.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/monthly-memory-gb-seconds`	GET	Yes

Example Response JSON


{
  "effectiveValue": 0,
  "planDefault": 0,
  "overrideValue": 0,
  "ceiling": 0,
  "userConfigurable": true
}

Set the monthly memory GB-seconds allowance. Setting an expiry requires an admin token.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/monthly-memory-gb-seconds`	PUT	Yes

Example Request JSON


{
  "value": 0,
  "expiresAt": "2019-08-24T14:15:22Z"
}

Example Response JSON


{
  "effectiveValue": 0,
  "planDefault": 0,
  "overrideValue": 0,
  "ceiling": 0,
  "userConfigurable": true
}

Clear the monthly memory GB-seconds allowance override.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/monthly-memory-gb-seconds`	DELETE	Yes

Example Response JSON


{
  "effectiveValue": 0,
  "planDefault": 0,
  "overrideValue": 0,
  "ceiling": 0,
  "userConfigurable": true
}

Create an impersonation token for a target account

Path	Method	Protected
`/v1/admin/impersonate/{account_id}`	POST	Yes

Creates a short-lived token that, when used for authentication, produces an AdminImpersonation auth context: access and visibility checks run as the target account, but audit writes (created_by fields) record the admin’s account ID.

Only users with the Admin account role may call this endpoint.

Example Request JSON


{
  "expiresAt": "2019-08-24T14:15:22Z"
}

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "secret": "stringstringstri",
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "createdAt": "2019-08-24T14:15:22Z",
  "expiresAt": "2019-08-24T14:15:22Z"
}

Account API Errors

Status Code	Description	Body
400	Invalid request, returning with a list of issues detected in the request	`{"code":"string","errors":["string"]}`
401	Unauthorized request	`{"code":"string","error":"string"}`
403	Forbidden Request	`{"code":"string","error":"string"}`
404	Entity not found	`{"code":"string","error":"string"}`
409		`{"code":"string","error":"string"}`
422	Limits of the plan exceeded	`{"code":"string","error":"string"}`
500	Internal server error	`{"code":"string","error":"string"}`