> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grdd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner Impersonation

> How a vendor platform (VP) company gets a core token for one of its client companies with POST /api/token/imp.

## Partner Impersonation API

A **vendor platform (VP)** company is a company with company type `VP`. Its
client companies are operator companies (company type `CO` or `IO`) that use the
same vendor platform.

With `POST /api/token/imp`, a signed-in user of a VP company gets a core
access token for one of its client companies. You do not need the client's
password. Core decides from the company records that it stores.

<Warning>
  The token that core issues is a full `MANAGER` token for the client company. It
  is not limited to a scope, and its claims do not identify the VP user who asked
  for it. Store it as carefully as a client password. Ask for it only when you
  must act for that client.
</Warning>

***

## Rules

Core issues the token only when all of these conditions are true. Core reads
each value from its stored company records, not from your request:

1. Your company is active.
2. Your company type is `VP`.
3. The client company is active.
4. The client company type is `CO` or `IO`. A `VP` company cannot be a target.
5. Both companies have a vendor platform value, and the two values are the same.
   Core ignores letter case and spaces at the start and end.
6. The shared vendor platform is not `api`.

Any signed-in user of a VP company that meets these rules can use the route.
Core does not require a specific role.

If a rule fails, core returns the same `403` response for every cause. The
response does not tell you whether the client company exists or is inactive.

### Platform administrators

GRiDD platform administrators (role `ADMIN`) are handled separately. For an
`ADMIN` caller, core does not apply the vendor-platform rules above. It requires
only that the target company exists and is active. This path is for GRiDD
staff, not for integrators.

***

## Endpoint

`POST https://core.grdd.net/api/token/imp`

### Headers

```http theme={null}
Authorization: Bearer <your access token>
Content-Type: application/json
```

Get your access token with [`POST /api/token`](/connect-api/get-token) as a user
of your VP company.

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `griddid` | string | Yes | The GNET ID of the client company. |

Core ignores other fields in the body.

```bash theme={null}
curl -X POST "https://core.grdd.net/api/token/imp" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"griddid":"latest"}'
```

### Success response (200)

```json theme={null}
{
  "success": true,
  "exp": 1786233600,
  "token": "CLIENT_ACCESS_TOKEN",
  "user": {
    "iss": "grdd.net",
    "vendor_platform": "YOUR_VENDOR_PLATFORM",
    "aud": "latest",
    "exp": 1786233600,
    "roles": ["MANAGER"],
    "iat": 1785628800,
    "username": "latest_drew_transpoapp"
  }
}
```

| Field | Type | Description |
| - | - | - |
| `success` | boolean | `true` when core issued the token. |
| `exp` | number | Expiry time, in seconds since the Unix epoch. The token is valid for 7 days. |
| `token` | string | The access token (JWT) for the client company. |
| `user` | object | The token claims. `aud` is the client GNET ID in lowercase. `roles` is always `["MANAGER"]`. `vendor_platform` is the vendor platform of the client company. |

### What the token is

* The token belongs to a **service username** for the client company, not to a
  person. For a VP caller, the username is `<griddid>_drew_transpoapp`, where
  `<griddid>` is the client GNET ID in lowercase. For an `ADMIN` caller, it is
  `<griddid>_support`, using the target ID's supplied casing in the current implementation.
* The username has no password and no user record of its own.
* The role is always `MANAGER` for the client company.
* The response does not contain a legacy token.
* Each call issues a new token. A new call does not revoke tokens that core
  issued before.

***

## Use the token

Send the token on core routes as `Authorization: Bearer <token>`. Core then acts
as a `MANAGER` of the client company.

<Note>
  To verify the token with [`GET /api/token`](/connect-api/get-token#verify-a-token),
  send it in the `token` header. In source, the `Authorization: Bearer` form of
  `GET /api/token` requires an enabled user record, and the service username has
  none. That form rejects the token with `401`.
</Note>

***

## Error responses

| Status | Body | Cause |
| - | - | - |
| `400` | `{"success": false, "message": "Invalid JSON body"}` | The body is not valid JSON. |
| `401` | `{"success": false, "message": "Unauthorized"}` | No token, or core could not identify the caller from the token. |
| `401` | `{"success": false, "message": "Unauthorized. missing credentials"}` | `griddid` is missing, empty, or not a string. |
| `403` | `{"success": false, "message": "Unauthorized"}` | A [rule](#rules) failed. |
| `403` | `{"success": false, "message": "Company is inactive"}` | The target company is not active. This specific response applies to the `ADMIN` path; VP callers receive the generic authorization denial. |
| `404` | `{"success": false, "message": "company not found :<griddid>"}` | Core has no record for the target company. This specific response applies to the `ADMIN` path; VP callers receive the generic authorization denial. |
| `500` | `{"success": false}` | Core could not complete the request. |

***

## Related pages

* [Get Token](/connect-api/get-token)
* [Core Operations overview](/connect-api/core/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.