Manage the partner integrations attached to your customers' accounts from your backend.
The In-App API lets your backend manage the partner integrations attached to your customers' accounts: attach an integration, update its status, list an account's integrations, or remove one. The in-app marketplace uses each integration's status to show the right buttons on each listing (see Buttons & Actions).
Requests are made on behalf of a signed-in user of your product, with the same kind of JWT the marketplace uses for SSO. See Authentication below.
Base URL
https://<your-marketplace>.partnerfleet.app/in_appEndpoint paths start with /api/in_app. You can also use your marketplace's custom domain.
Endpoints
| Method | Path | Does |
|---|---|---|
GET | /api/in_app/attached_integrations | Lists the integrations attached to the authenticated user's account. |
POST | /api/in_app/attached_integrations | Attaches a new integration, or updates the status of an existing one, for the current account. |
DELETE | /api/in_app/attached_integrations?partner=<partner> | Removes the integration between the current account and the partner. |
Authentication
Every In-App API request carries a JWT that your backend signs for the signed-in user. It is the same kind of token your application generates for the in-app marketplace's SSO, described in JWT SSO Implementation.
Authorization: Bearer <jwt>Signing the token
- Algorithm: HS256 (HMAC SHA-256). Other algorithms are not supported.
- Secret: the shared secret under Settings > In-App Marketplace > Developer Settings > JWT Identity Provider (see Developer Settings). Keep it on your server; never expose it in client-side code.
- Expiration: every token must include
exp. Set it more than 5 minutes after the token is generated.
Claims
| Claim | Required | Meaning |
|---|---|---|
email | Yes | Unique identifier for the user. |
ufn | Yes | The user's first name. |
uln | Yes | The user's last name. |
account.external_id | Yes | Unique identifier for the user's account. |
account.name | Yes | The account's display name. |
Other account keys | No | Account-level custom fields, such as tier or region. |
fields | No | User-level custom fields, such as user_type. |
exp | Yes | Expiry, as a Unix timestamp. |
Example payload:
{
"email": "[email protected]",
"ufn": "FirstName",
"uln": "LastName",
"fields": { "user_type": "Admin" },
"account": {
"external_id": "123456789",
"name": "Account Name",
"tier": "Enterprise",
"region": "North America"
},
"exp": 1234567890
}Field names and values must match your PartnerFleet admin configuration exactly; casing matters. The account in the token is the "current account" the endpoints act on.
Test your tokens
Use Settings > In-App Marketplace > Test Tools to generate test tokens and to decode the tokens your backend produces, so you can check field names, values and signatures. Ruby, Node.js and Python signing examples are in JWT SSO Implementation.
Integration statuses
Statuses like Active, Pending, Errored and Disabled are supported by default, but can be customized for your marketplace. Send the status name exactly as it is configured.
Passing status when the marketplace loads
You can also pass each user's integration statuses when the marketplace first renders, through the embed script's integrations array. See Embed Script Implementation.
Errors
A request with a missing or invalid token returns 401 Unauthorized.