Get a token for a specific user

Overview

Issue a token that acts as a specific user at a partner or account.

Use this to see exactly what one person sees, for example to debug a permissions question.

You'll need the user_id of the user to act as, or the company_id of an account to act as its owner.

Returns a token that acts as that user, with the same sign-in details a login returns (user, company, theme_options, white_label).

Prerequisites

A bearer token. See Authentication.
The user's id, from List users, or the account's id, from List accounts.

Base URL

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

Endpoint

POST /api/v1/users/impersonate

Authentication

Partner or Account token

The user must be inside your own account tree. A Partner token reaches users at your partner and in any account or location under it; an Account token reaches users at your account and its locations. Anyone else returns 403.
A token from this call remembers who started the session. With it you can act as anyone inside that original user's tree, or switch back to the original user (you then get a normal token again), but never outside it.
Inside your own company, you can only act as someone who ranks below you (Owner, then Admin User, then User, Brand Assigned and Location Assigned, then Basic User). For example, a Basic User can't act as their company's Owner. Users in accounts or locations further down your tree aren't limited by rank.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Notes
`user_id`	integer	Yes, unless you send `company_id`	The user to act as. Must exist.
`company_id`	integer	Yes, unless you send `user_id`	An account to act as its owner. Must exist.

Send exactly one of the two fields. Leave the other out entirely: sending it as null fails validation with 422 (The selected company id is invalid.). If you send both, user_id is used.

Request payload

{
  "user_id": 3011
}

To act as an account's owner, send {"company_id": 5994} instead.

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`token`	string	The bearer token for the user. Send it as `Authorization: Bearer <token>`.
`login_type`	string	`impersonate`.
`user.id`	integer	User id.
`user.username`	string	Username.
`user.email`	string	Email address.
`user.phone_number`	string or null	Phone number.
`user.first_name`	string	First name. Empty string when not set.
`user.last_name`	string	Last name. Empty string when not set.
`user.title`	string	Job title. Empty string when not set.
`user.role`	string	One of `Owner`, `Admin User`, `Basic User`, `Brand Assigned`, `Location Assigned`, `User`.
`user.total_location`	integer	Number of locations the user can reach. `0` for a partner user.
`company.id`	integer	The user's company id.
`company.name`	string	Company name.
`company.bundle_id`	integer	Company level: `1` partner, `3` account, `2` location.
`company.company_option`	object or null	`company_id`, `who_will_pay` (string) and `enable_generic_alert` (boolean).
`theme_options`	string or null	Theme settings as a JSON-encoded string.
`white_label`	object	`logo`, `white_url`, `favicon`, `title`, `status`, `login_logo`, `company_id` and `email_templates_enabled` (boolean). With no branding set anywhere up the account tree, the defaults are `logo`, `favicon` and `login_logo` empty, `status` `inactive`, `company_id` `null`, and `title` the platform name.

Response payload

{
  "data": {
    "status": "success",
    "token": "<access-token>",
    "login_type": "impersonate",
    "user": {
      "id": 3011,
      "username": "Jane",
      "email": "[email protected]",
      "phone_number": null,
      "first_name": "Jane",
      "last_name": "Smith",
      "title": "Manager",
      "role": "Owner",
      "total_location": 2
    },
    "company": {
      "id": 5994,
      "name": "Acme Coffee",
      "bundle_id": 3,
      "company_option": {
        "company_id": 5994,
        "who_will_pay": "partner",
        "enable_generic_alert": false
      }
    },
    "theme_options": "{\"mode\":\"system\",\"skin\":\"default\",\"layout\":\"vertical\",\"primaryColor\":\"#f1874c\"}",
    "white_label": {
      "logo": "https://d2ny6zb7otrnhl.cloudfront.net/white-label/logo/example.png",
      "white_url": "https://production.shoutaboutus.com",
      "favicon": "https://d2ny6zb7otrnhl.cloudfront.net/white-label/favicon/example.png",
      "title": "Acme Reviews",
      "status": "active",
      "login_logo": "",
      "company_id": 5,
      "email_templates_enabled": true
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

403 Outside your tree, or not below you

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

403 Email not verified

The user hasn't verified their email address yet.

{
  "message": "Forbidden",
  "status": "error",
  "errors": "Email not verified. Please verify your email to continue."
}

404 User not found

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

404 Account has no owner

{
  "message": "Not Found",
  "status": "error",
  "errors": "No owner user found for the given company"
}

422 Neither id sent

{
  "message": "The user id field is required when company id is not present. (and 1 more error)",
  "errors": {
    "user_id": [
      "The user id field is required when company id is not present."
    ],
    "company_id": [
      "The company id field is required when user id is not present."
    ]
  }
}

422 Unused field sent as null

{
  "message": "The selected company id is invalid.",
  "errors": {
    "company_id": [
      "The selected company id is invalid."
    ]
  }
}

Status	Meaning
`200`	The token and sign-in details for the user.
`401`	The token is missing, expired or invalid.
`403`	The user is outside your tree, ranks the same as or above you in your own company, or hasn't verified their email.
`404`	The user, the account or the account's owner can't be found.
`422`	Neither id is supplied, an id doesn't exist, or an unused field is sent as `null`.
`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": 3011}'