Impersonation Tokens

Impersonation tokens are workspace-level API tokens that can act on behalf of any member of the workspace. A Workspace Admin creates one token and uses it for multiple users. All interactions with impersonation tokens happen through the API, not the UI.

To enable impersonation tokens for your workspace, email [email protected].

Endpoint	Purpose
`POST /api/v1/api-tokens/impersonation`	Create a token
`GET /api/v1/api-tokens/impersonation`	List all tokens
`DELETE /api/v1/api-tokens/impersonation/{id}`	Delete a token

Create an impersonation token

POST /api/v1/api-tokens/impersonation

No fields are required. Two optional fields are accepted:

Field	Description
`name`	A label for the token. It is returned by the list endpoint and helps distinguish tokens from each other.
`roles`	The scoped roles the token will have. By default, the token has full read/write access. Use `default` or `:` for read/write, `read:*` for read-only.

Request

{
  "name": "XYZ Integration Token",
  "roles": ["read:*"]
}

The example above creates a read-only token.

Response

The most important field in the response is token, which you use in API calls. The id is what you need to delete the token later.

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

List all impersonation tokens

GET /api/v1/api-tokens/impersonation

The response is an array of tokens, each with its ID, a masked token string, name, and creation date.

[
  {
    "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"
  }
]

Delete an impersonation token

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

There is no request or response body for this call.

Use an impersonation token

Pass the token returned at creation in the Authorization header as a Bearer token. You must also specify which user is being impersonated, in one of two ways.

Option 1: the X-Guru-UserID header. Add a header named X-Guru-UserID whose value is the email address or user ID of the user 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]'

Option 2: append to the token. Append the user's email address or user ID to the end of the token in the Authorization header, separated by a :.

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