> ## Documentation Index > Fetch the complete documentation index at: https://docs.vortexiq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Authentication > How to authenticate against the StagingPro V2 Migration API - bearer tokens for scripts and services, or your signed-in session from the browser. The StagingPro V2 Migration API is served from `https://app.vortexiq.ai/v2/api/bc-migration`. Every request is authenticated as a Vortex IQ user and scoped to a single organisation. Two authentication methods are supported, and every endpoint accepts either: | Method | Best for | How it travels | | ---------------- | --------------------------------------------- | -------------------------------------- | | **Bearer token** | Scripts, CI, backend services | `Authorization: Bearer ` header | | **Session** | Calls from a signed-in `app.vortexiq.ai` page | Session cookie, automatically | ## Bearer tokens (server-to-server) Exchange your identity and your organisation's API credential for a token on the [Login](/vortex-apps/staging-pro/api/login) endpoint: ```bash theme={null} curl -X POST https://app.vortexiq.ai/v2/api/bc-migration/login \ -H "Content-Type: application/json" \ -d '{ "username": "Jane Merchant", "email": "jane@example.com", "organization_name": "Example Retail Ltd", "client_id": "viq_bcmig_Ab12Cd34Ef56Gh78Ij90Kl12", "client_secret": "" }' ``` A successful login returns your user and organisation details, the BigCommerce stores connected to your organisation (source material for every other endpoint), and the token itself: ```json theme={null} { "user": { "email": "jane@example.com", "first_name": "Jane", "last_name": "Merchant" }, "organization": { "id": 42, "name": "Example Retail Ltd" }, "stores": [ { "integration_id": 101, "store_hash": "abc123xyz", "name": "Production Store", "environment_type": "production", "is_production": true }, { "integration_id": 102, "store_hash": "def456uvw", "name": "Staging Store", "environment_type": "staging", "is_production": false } ], "token_type": "Bearer", "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "expires_in": 864000, "expires_at": "2026-07-27T14:46:16+00:00" } ``` Send the token on every subsequent call: ```bash theme={null} curl https://app.vortexiq.ai/v2/api/bc-migration/migrations \ -H "Authorization: Bearer " ``` ### What you need before you can log in The `client_id` / `client_secret` pair is issued per organisation by Vortex IQ. The secret is shown once at issue time - store it in a secret manager, never in client-side code. Contact [support](https://www.vortexiq.ai/contact-us) to have a credential provisioned or rotated. The app is enabled per organisation; without it every endpoint returns `403`. A migration needs a source and a destination, so login refuses organisations with fewer than 2 connected stores (`403 insufficient_stores`). ### Token lifetime and revocation * Tokens live for **10 days** (`expires_in: 864000`). Log in again to get a fresh one - there is no refresh endpoint. * **Rotating or disabling** your organisation's API credential immediately invalidates every outstanding token for the organisation, not just future logins. Rotation keeps the same `client_id`; only the secret changes. * A token is bound to the user and organisation it was issued for. If the user leaves the organisation, the token stops working. * The token is a signed JWT: its claims are readable (no secrets inside), but any modification invalidates it. Treat the whole token as a secret - it authenticates as you. * Login is rate limited to **10 attempts per minute** (`429` beyond that), and failed logins return a deliberately generic `401 invalid_credentials` that does not reveal which field was wrong. ## Sessions (from the browser) Requests from a signed-in `app.vortexiq.ai` page are authorised by your Vortex IQ session, the same one the StagingPro UI uses - no token needed: ```js theme={null} // From a signed-in app.vortexiq.ai page - the session cookie travels automatically. const res = await fetch('/v2/api/bc-migration/migrations'); const { migrations } = await res.json(); ``` The same organisation gate applies: if Store Migration is not enabled for your organisation, every endpoint returns `403`: ```json theme={null} { "message": "Store Migration is not enabled for this organization." } ``` Everything you read or start is scoped to your organisation. Migration history shows only your organisation's runs, and a store must be connected to your organisation before you can migrate it - otherwise you get `422 store_not_found`. ## Store credentials You never send BigCommerce API tokens to this API. Stores are referenced by **store hash** - for example `"source_store_hash": "abc123xyz"`. The hashes for your organisation's stores are returned by [Login](/vortex-apps/staging-pro/api/login). Vortex IQ resolves each store's BigCommerce credentials server-side from your organisation's connected StagingPro integrations, and authorises the store against your organisation on every call. Tokens never travel through the browser, your scripts, or this API's request bodies. This is why connecting a store in StagingPro is a prerequisite for migrating it, and why a hash your organisation has not connected returns: ```json theme={null} { "error": "store_not_found", "message": "source or destination store not found / not authorized for this organization" } ``` ## Errors you may hit | Status | Meaning | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` | Login: one of the provided values could not be validated (deliberately unspecific). Other endpoints: missing, expired, tampered, or revoked bearer token, and no valid session. | | `403` | Store Migration is not enabled for your organisation, or (on login) fewer than 2 connected stores. | | `422` | A store hash is unknown or not connected to your organisation, or the request failed validation. | | `429` | Login rate limit exceeded (10 per minute). | | `502` | The migration service or BigCommerce could not be reached. | | `503` | API access is not configured on this environment. |