Impersonate user or company owner

Overview

Issue a login token that lets the caller act as another user or a company's owner. Partners (bundle_id=1) may impersonate users/owners of their child companies; accounts (bundle_id=3) may impersonate users of their parent partner. Every attempt (grant + denial) is audited (AUTH_IMPERSONATE). Send user_id or company_id (each is required_without the other); if both are sent, user_id takes precedence.

Prerequisites

A bearer token in the Authorization header.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/users/impersonate

Authentication

Requires a bearer token in the Authorization: Bearer <bearer-token> header.
Partner or account — collection bearer token. Unauthorized targets return 403.

Rate limit

No rate limit.

Request body

Field	Type	Required	Description
`user_id`	integer	Required without `company_id`	Id of the user to impersonate.
`company_id`	integer	Required without `user_id`	Id of the company whose owner to impersonate.

{
  "user_id": 9,
  "company_id": null
}

How it works

200 returns a full login payload for the impersonated identity (token, login_type=impersonate, user, company, theme_options, white_label).
403 when the target is not within the caller's permitted tree.
404 when the user/company/owner cannot be found; 422 when neither id is supplied.

Response

200 OK · `200`

{
  "data": {
    "status": "success",
    "token": "<access-token>",
    "login_type": "impersonate",
    "user": {
      "id": 9,
      "username": "John",
      "email": "[email protected]",
      "phone_number": null,
      "first_name": "John",
      "last_name": "Doe",
      "title": "Manager",
      "role": "Brand Assigned",
      "total_location": 0
    },
    "company": {
      "id": 5,
      "name": "Acme Partner",
      "bundle_id": 1,
      "company_option": {
        "company_id": 5,
        "who_will_pay": "partner",
        "enable_generic_alert": false
      }
    },
    "theme_options": "{\"mode\":\"system\",\"skin\":\"default\",\"layout\":\"vertical\",\"primaryColor\":\"#f1874c\"}",
    "white_label": {
      "logo": "https://cdn.example.com/logo.png",
      "white_url": "https://portal.example.com",
      "favicon": "https://cdn.example.com/favicon.png",
      "title": "Acme",
      "status": "active",
      "login_logo": "",
      "company_id": 5,
      "email_templates_enabled": true
    }
  }
}

403 Not authorized · `403`

{
  "message": "Forbidden",
  "status": "error",
  "errors": "You are not authorized to impersonate this user"
}

404 Not found · `404`

{
  "message": "Not Found",
  "status": "error",
  "errors": "User not found"
}

Errors

Status	Meaning
`401`	The bearer token is missing, expired or invalid
`403`	Not authorized
`404`	Not found
`422`	Returned when neither id is supplied
`500`	Unexpected server error

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/users/impersonate" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"user_id": 9, "company_id": null}'

Updated 11 days ago

Did this page help you?