Skip to content

Accounts

Account endpoints are not available via OAuth — account management requires a session or API-key credential.

List All Accounts

This is not account scoped and will return ALL accounts this user has access to.

GET /api/accounts

Returned Params
  • accounts: Array
    • id: String
    • name: String
    • reseller: Boolean
    • is_trial: Boolean
    • trial_start: DateTime
    • trial_end: DateTime
    • parent_account: Object | sub-accounts only — see the warning below
      • id: String
      • name: String
    • reseller_billing_plan: Object | sub-accounts with a reseller billing plan only — see the warning below
      • id: String
      • name: String
    • nameservers: Array
    • created_at
    • updated_at

parent_account and reseller_billing_plan are absent, not null

When an account has no parent, neither key appears in the JSON at all — and reseller_billing_plan is likewise absent whenever parent_account is absent, even if the account has a plan. Test for key presence rather than for a null value; a client that reads account["parent_account"]["id"] on a top-level account will fail on the missing key, not on a null.

The list does not include account_roles

Account roles are returned by View Account and by List Account Roles — not by GET /api/accounts.

View Account

GET /api/accounts/:id

Returns a single account object with all the fields of a list entry plus account_roles, which the list does not return. Each entry in account_roles has the same shape as an entry in List Account Roles. Returns 401 if the token's user cannot view the account.

Create Account

Two modes:

  • Top-level account — omit X-Auth-Account. Requires an admin user.
  • Sub-account — set X-Auth-Account to the parent Account ID. Requires an admin role on the parent and the parent must be a reseller.

POST /api/accounts

Params
  • account: Object
    • name: String (required)

Admin-only params

Admin callers may additionally set is_trial, trial_start, trial_end, reseller, reseller_bill_trial, billing_plan_id, and parent_account_guid.

Returns 201 with the account on success.

Update Account

PATCH /api/accounts/:id

Requires edit permission. Non-admin callers can only update name. Admin callers may additionally set is_trial, trial_start, trial_end, reseller, reseller_bill_trial, billing_plan_id, and parent_account_guid. Returns 202.

Params
  • account: Object
    • name: String

Delete Account

DELETE /api/accounts/:id

Requires destroy permission. Returns 202.

Cannot delete your only account

A non-admin user cannot delete their last remaining account, even with can_destroy on it — the request returns 401 (Not Authorized). The user must have at least one other account.

Account Roles

Manage which users have access to an account, and at what role. Requires an admin role on the account. Not available via OAuth.

List Account Roles

GET /api/accounts/:account_id/roles

Returned Params
  • account_roles: Array<Object>
    • inherited_from: String | account id, or null
    • created_at: DateTime
    • updated_at: DateTime
    • role: Object
      • id: Integer
      • name: String
      • label: String
      • is_admin: Boolean
      • can_edit: Boolean
      • can_create: Boolean
      • can_destroy: Boolean
      • billing: Boolean
      • wp_login: Boolean
    • user: Object
      • id: String
      • fname: String
      • lname: String
      • email: String
      • account_brand_id: Integer
      • locale: String
      • created_at: DateTime
      • updated_at: DateTime

View a User's Role

GET /api/accounts/:account_id/roles/:user_id

Returns one entry, wrapped in a single account_role object rather than the account_roles array the list returns.

Returned Params
  • account_role: Object
    • inherited_from: String | account id, or null
    • created_at: DateTime
    • updated_at: DateTime
    • role: Object
      • id: Integer
      • name: String
      • label: String
      • is_admin: Boolean
      • can_edit: Boolean
      • can_create: Boolean
      • can_destroy: Boolean
      • billing: Boolean
      • wp_login: Boolean
    • user: Object
      • id: String
      • fname: String
      • lname: String
      • email: String
      • account_brand_id: Integer
      • locale: String
      • created_at: DateTime
      • updated_at: DateTime

Invite a User

Invite an existing user to the account by email. Returns 202.

POST /api/accounts/:account_id/roles

Params
  • email: String
  • user_role_id: Integer | see User Roles

Change a User's Role

PATCH /api/accounts/:account_id/roles/:user_id

Params
  • account_role: Object
    • user_role_id: Integer

Returns the updated role in the same shape as GET /api/accounts/:account_id/roles/:user_id.

Returned Params
  • account_role: Object
    • inherited_from: String | account id, or null
    • created_at: DateTime
    • updated_at: DateTime
    • role: Object
      • id: Integer
      • name: String
      • label: String
      • is_admin: Boolean
      • can_edit: Boolean
      • can_create: Boolean
      • can_destroy: Boolean
      • billing: Boolean
      • wp_login: Boolean
    • user: Object
      • id: String
      • fname: String
      • lname: String
      • email: String
      • account_brand_id: Integer
      • locale: String
      • created_at: DateTime
      • updated_at: DateTime

Remove a User

DELETE /api/accounts/:account_id/roles/:user_id

Returns 202.

Inherited roles

A role inherited from a parent account cannot be removed at the child level — doing so returns 422 {"errors":["Unable to remove an inherited role."]}. Change the parent role to update all descendants.

User Roles

List the available role definitions. Use the returned id when inviting or updating users on an account.

GET /api/user_roles

Returned Params
  • user_roles: Array<Object>
    • id: Integer
    • name: String
    • label: String
    • is_admin: Boolean
    • can_edit: Boolean
    • can_create: Boolean
    • can_destroy: Boolean
    • billing: Boolean
    • wp_login: Boolean