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
      • id: String
      • name: String
    • reseller_billing_plan: Object
      • id: String
      • name: String
    • account_roles: Array<Object>
      • inherited_from: String | ID of the account a role is inherited from, else null
      • 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
      • created_at: DateTime
      • updated_at: DateTime
    • nameservers: Array
    • created_at
    • updated_at

View Account

GET /api/accounts/:id

Returns a single account object with the same fields as a list entry. 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
      • created_at: DateTime
      • updated_at: DateTime

View a User's Role

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

Returns the same shape as a single list entry.

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

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