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

# Store and user context

> The default-granted endpoint every installed app can call first: read the store's identity and the installing user from GET /app/context, with no OAuth scope required.

## Overview

`GET /api/v1/app/context` returns the identity of the store your app is installed on and the
merchant who installed it. It is **default-granted to every installation**: no OAuth scope is
required, because it exposes only the store profile an app needs to render its own header.

Call it **first**, before any scoped endpoint, to display the store's name, logo, currency,
country and storefront domain, and to learn whether the installing user is the owner or a staff
member.

```http theme={null}
GET /api/v1/app/context
Authorization: Bearer app_<your-app-access-token>
```

## Authentication

Send your `app_` access token as a Bearer header. This endpoint accepts an **app token only**. A
merchant session is refused with `403`, because the response is the store the app is installed on,
not the store a person happens to be browsing.

The store comes from the **installation bound to your token**, never from a header or query
parameter. There is no `x-shop-id` here: a token can only ever read the one store it was installed
on.

## Response

```json theme={null}
{
  "status": 200,
  "success": true,
  "message": "Context retrieved",
  "data": {
    "app": {
      "id": "66f0aabbccddeeff00112233",
      "clientId": "app_7d1f0c2b9a4e4f6c8b3d2a1e0f9c8b7a",
      "installationId": "66f1bbccddeeff00112233445",
      "name": "Acme Analytics",
      "slug": "acme-analytics"
    },
    "store": {
      "id": "6680aabbccddeeff00112200",
      "name": "Acme Store",
      "type": "restaurant",
      "domain": "acme.store",
      "url": "https://acme.store",
      "logo": "https://cdn.salesive.com/stores/acme/logo.png",
      "favicon": "https://cdn.salesive.com/stores/acme/favicon.png",
      "tagline": "Best jollof in town",
      "description": "Lagos kitchen, open every day",
      "currency": { "code": "NGN", "symbol": "₦", "name": "Nigerian Naira" },
      "country": { "name": "Nigeria", "code": "NG", "flag": "https://cdn.salesive.com/flags/ng.svg" },
      "state": "Lagos",
      "location": {
        "address": "12 Lekki Phase 1",
        "city": "Lagos",
        "state": "Lagos",
        "country": "Nigeria",
        "phone": "+2348012345678",
        "email": "hello@acme.com",
        "zipCode": "106104",
        "coordinates": { "lat": 6.4474, "lng": 3.4735 }
      },
      "business": {
        "name": "Acme Ltd",
        "phone": "+2348012345678",
        "email": "billing@acme.com"
      },
      "socialMedia": {
        "facebook": "https://facebook.com/acmestore",
        "instagram": "https://instagram.com/acmestore",
        "x": "https://x.com/acmestore",
        "tiktok": "https://tiktok.com/@acmestore"
      }
    },
    "user": {
      "id": "66b1f0a3c2d4e5f6a7b8c9d0",
      "name": "Amara Okonkwo",
      "email": "amara@acme.com",
      "phone": "+2348012345678",
      "avatar": "https://cdn.salesive.com/avatars/amara.png",
      "storeRole": "owner"
    }
  }
}
```

### app

| Field | Type | Description |
| - | - | - |
| `id` | string | Your app's registration id. It is the same on every store, and it is the id in the developer console URL, `/apps/developer/<id>`. |
| `clientId` | string or `null` | Your OAuth client id, `app_<hex>`. |
| `installationId` | string | This store's installation id. Use it when you need the per-store record. |
| `name` | string | Your app's name. |
| `slug` | string or `null` | Your marketplace slug, when set. |

`id` and `clientId` are stable across every store. `installationId` changes with each install. The
app id is the value the scripts API accepts as `integration`, so an app never has to hardcode or
guess it. See [Create a script](https://docs.salesive.com/apps-api/endpoint/scripts/create-script.md).

### store

| Field | Type | Description |
| - | - | - |
| `id` | string | The store id. The same value as `shopId` on every webhook. |
| `name` | string | The store's display name. |
| `type` | string | `ecommerce`, `restaurant`, `business` or `digital`. Use it to decide which catalog your app should read. |
| `domain` | string or `null` | The storefront host, for example `acme.store`. `null` when the store has no domain. |
| `url` | string or `null` | The storefront URL: `https://` plus `domain`, with no trailing slash. `null` when the store has no domain. |
| `logo` | string | Store logo URL. |
| `favicon` | string | Store favicon URL. |
| `tagline` | string or `null` | Short store tagline, when set. |
| `description` | string or `null` | Longer store description, when set. |
| `currency` | object or `null` | The store's currency as `{ code, symbol, name }`, when one is set. |
| `country` | object or `null` | The store's country as `{ name, code, flag }`, where `flag` is the flag image when the country record carries one. |
| `state` | string or `null` | The store's state or region, when set. |
| `location` | object or `null` | The store's address block, or `null` when no location is recorded. |
| `location.address` | string or `null` | Street address. |
| `location.city` | string or `null` | City. |
| `location.state` | string or `null` | State or region. |
| `location.country` | string or `null` | Country name, as recorded on the address. |
| `location.phone` | string or `null` | Contact phone. |
| `location.email` | string or `null` | Contact email. |
| `location.zipCode` | string or `null` | Postal code. |
| `location.coordinates` | object or `null` | `{ lat, lng }`, or `null` when no latitude is recorded. |
| `business` | object or `null` | Business details as `{ name, phone, email }`, each a string or `null`. |
| `socialMedia` | object or `null` | The store's social links. The object can carry `facebook`, `instagram`, `x` and `tiktok`, each a string. |

The storefront domain is resolved from the store's own domains in this order: the default
domain first, then an active custom domain, then any other active domain. When none of those is
available it falls back to the store's legacy domain field. `domain` and `url` are both `null`
when the store has no domain at all.

Use `store.url` to build product links, emails and canonical URLs. Do not ask the merchant to
type a domain: this is the storefront they have already set up, and a hardcoded value goes stale
when they change it.

Every field inside `location` and `business` is returned as `null` when it is not set, so the
object shape stays stable. `socialMedia` is the store's own object and its keys vary by store.

### user

| Field | Type | Description |
| - | - | - |
| `id` | string | The Salesive user who installed your app. |
| `name` | string | Their name. |
| `email` | string | Their email. |
| `phone` | string or `null` | Their phone, when set. |
| `avatar` | string or `null` | Their avatar URL, when set. |
| `storeRole` | string | `owner` when the installing user owns the store, otherwise `staff`. |

`user` is the person who completed the install, not necessarily the person viewing your app right
now. Use `user.id` to bind your own session to that person, and compare it with the `?user=` value
the dashboard appends to your iframe URL. See [Install your app](https://docs.salesive.com/apps/oauth-install.md).

> [!NOTE]
>
> This endpoint is for identity, not for store data. It carries no orders, customers, products,
> financial balances or credentials. Read those from their own endpoints with the matching scope.

## When to call it

* **On first load**, to render the store's name, logo, currency, country and storefront domain
  without asking the merchant for a scope.
* **When you need a link**, to build product links, emails and canonical URLs from `store.url`
  rather than asking the merchant to type a domain.
* **After a `shop/updated` webhook**, to pick up a change to the profile, business details,
  location or app info. The event carries a `section` field naming the part that changed and no
  values, so re-fetch them here. See [Webhooks](https://docs.salesive.com/apps-api/webhooks.md).
* **When binding a session**, to record which user installed the app and whether they are the
  owner or staff.
* **When you need your own id**, read `app.id` instead of hardcoding it. The scripts API and any
  support or billing link can use it.

## Errors

| Status | Meaning |
| - | - |
| `401` | The token is missing, expired or revoked, or the app is no longer installed on the store. |
| `403` | The caller is not an app token. The message is `This endpoint requires an app token.` |
| `404` | The store bound to the installation no longer exists. |

## Next steps

> [card] [Scopes & permissions](https://docs.salesive.com/apps/scopes-permissions.md)
>
> The default grant and every scope an app can request.

> [card] [Webhooks](https://docs.salesive.com/apps-api/webhooks.md)
>
> The `shop/updated` topic and the rest of the event list.

> [card] [Install your app](https://docs.salesive.com/apps/oauth-install.md)
>
> Exchange the install for a token and bind your session to `user.id`.

> [card] [Apps API overview](https://docs.salesive.com/apps-api/introduction.md)
>
> Authentication, the response envelope and money units.


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