Impersonation Tokens

Impersonation tokens are Workspace level API tokens that can impersonate any member of the Workspace. A Workspace Admin can create an Impersonation token and use that token on behalf of multiple different users. All interactions with Impersonation tokens are done through the API - not the UI.

To start using Impersonation tokens, please email our Support Team today at [email protected].

Create a new Impersonation Token

POST /api/v1/api-tokens/impersonation

Request Body

There are no required fields when creating an Impersonation token. An optional name field is accepted to give a name/label to the token. This will be returned in the "list" endpoint and is helpful for distinguishing the tokens from each other. An optional roles field is accepted to specify the scoped roles the token will have. By default, the token will have full read/write access. More limited scopes can be applied to the token to limit what it can access.

Roles:

default or *:* - read/write
read:* - read only

{
  "name" : "XYZ Integration Token",
  "roles" : ["read:*"] //example of a read only token
}

Response

The most important thing the response will return is the token. This will be used in API calls. The id is useful for deleting an impersonation token.

{
  "id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 
  "name" : "XYZ Integration Token",
  "token" : "GINT:IMP:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "roles" : [ "read:*" ]
}

Delete an Impersonation Token

DELETE /api/v1/api-tokens/impersonation/{id}

There is no request or response body for this method.

List all Impersonation Tokens

GET /api/v1/api-tokens/impersonation

Response

The response will include an array of tokens, including the ID of the token, a masked token string, name, and date created.

[ 
  {
    "token" : "GINT:IMP:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxc622",
    "id" : "9e0b2b17-5a76-44ef-b726-09d556b04318",
    "roles" : [ "read:*" ],
    "dateCreated" : "2024-07-23T16:11:25.257+0000"
  }, {
    "token" : "GINT:IMP:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx60b0",
    "name" : "First Integration",
    "id" : "47e6a5b4-e91e-4af9-9893-a7793cbd49ca",
    "dateCreated" : "2024-07-23T23:55:21.788+0000"
  } 
]

Using an Impersonation Token

The token returned from Creating an Impersonation token can be used in the Authorization header as a Bearer token. In addition to the Authorization header, the caller must specify the user that is being impersonated. There are two ways to specify the user.

X-Guru-UserID header - this method includes adding an additional header to your call with the header name of X-Guru-UserID. The value of the header is the email address or user ID of the user you'd like to impersonate.

curl 'https://api.getguru.com/api/v1/whoami' \
   -H 'Authorization: Bearer GINT:IMP:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' 
   -H 'X-Guru-UserID: [email protected]'

Append to token - this method includes appending the user's email address or user ID at the end of the token in the Authorization header (including a : separator).

curl 'https://api.getguru.com/api/v1/whoami' \
   -H 'Authorization: Bearer GINT:IMP:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:[email protected]'