Authentication & credential architecture

Put the right credential in the right trust boundary.

Choose the exact Mappls product generation before handling a key or token. This center keeps current core REST, legacy OAuth, InTouch, browser/mobile keys, widgets, device activation, enterprise surfaces, and MCP identity separate—and stops when source evidence cannot safely decide.

Choose a path Manage credentials

Credential paths14Distinct placement and lifecycle boundaries

Client runtimes10Server, browser, native, device, widget, and MCP

REST evidence162Normalized contracts considered without inventing issuance

Credential-free1Deep links—and offline MCP discovery—need no provider key

Placement advisor

Start with product + runtime.

A variable name such as access_token is not enough. The same suite includes multiple generations and security planes.

One rule above all

Observable is not secret. Restricted is not universal.

Browser and mobile app keys can be inspected, so their safety comes from exact runtime restrictions. Trusted credentials stay behind a server boundary. Entitlement-only surfaces need their own issued contract.

Untrusted clients

Browser, mobile, shared wrappers

Only the explicitly documented public application credential. Restrict exact origin, package/signing identity, or bundle/team context.

public + runtime-restricted

Trusted compute

Server, job, gateway, MCP service

Managed secret provider, narrow adapter, redacted telemetry, bounded inputs, explicit product generation, and independent rotation.

secret + least privilege

No credential

Deep links and offline discovery

Do not add a token where the contract needs none. Bound public intent and keep sensitive workflow state in the application.

none

Full credential journey

Issue through reconciliation—not “copy and forget.”

Open console lifecycle

1 · Classify
Runtime, product, auth generation, region, data class, and trust boundary are explicit before a credential is requested.
2 · Issue
A non-production application owns the credential; one-time reveal is acknowledged and no value enters tickets, chat, screenshots, or source.
3 · Store
Secrets use a managed secret provider; public app keys live only in the intended client configuration and remain restricted.
4 · Restrict
Exact origins, server egress, Android package/signing identity, iOS bundle/team context, scope, region, and expiry are least-privilege.
5 · Exercise
Success, missing, denied, expired, rate-limited, revoked, offline, and release-build paths are tested without credential reflection.
6 · Rotate
A second version is issued, both versions are observed during a bounded overlap, consumers drain, and the prior version is revoked.
7 · Reconcile
Inventory, last-safe-use metadata, owner, expiry, restrictions, provider identity, and revocation state agree with the control plane.

Every security plane

14 placement paths

Open machine-readable catalog

Trusted secretTrusted Server

Current core REST from a trusted server

Use the current restricted static-key generation only inside a trusted process for current core location requests.

Generation: Current core REST
Credential: Restricted static key
Transport: Documented access_token query contract, applied internally by the trusted adapter
Evidence: 13 normalized operations · not-declared

Placement and restrictions

Allowed

Managed secret provider injected into a trusted process
Dedicated backend-for-frontend or policy-checked tool server
Separate non-production and production application identities

Never place here

Browser JavaScript, HTML, mobile bundle, desktop package, URL returned to a user, model context, logs, analytics, screenshots, or source
Generic proxy endpoints that accept arbitrary provider paths or parameters

Restrict and prove

Exact server egress identities and subscribed products
Query-string redaction at application, proxy, WAF, APM, and support boundaries
Explicit timeout, bounded idempotent retry, input/result limits, and safe request provenance

Rotation and failure recovery

Rotate safely

Issue a second restricted version
Deploy it behind the same adapter and observe safe success/error rates
Drain caches/workers, revoke the old version, and reconcile inventory

401 or authentication rejected

The credential generation, transport, host/path line, expiry, or product scope does not match the selected contract.

Stop retries; compare the issued credential class and exact contract, retain only a safe request identity, and test a new non-production credential after reconciliation.

403 or entitlement rejected

Authentication succeeded but the application, product, region, origin, package, bundle, asset, workspace, or operation is not allowed.

Keep the same credential shape and reconcile entitlement plus restrictions in the console; do not weaken restrictions blindly.

Works locally, fails in release

Release origin, signing certificate, bundle, egress address, build configuration, or environment injection differs from development.

Compare safe runtime identity to the registered restriction and prove the release artifact without printing the credential.

Trusted server adapter · typescript

const mappls = new MapplsClient({
  tokenProvider: envToken("MAPPLS_STATIC_KEY"),
  coreAuthentication: "static-query",
});

const result = await mappls.geocode({ address, region: "IND" });
// The SDK owns credential placement, timeout, bounded retry, and redaction.

Trusted secretTrusted Server

Legacy core REST OAuth generation

Preserve the pre-current OAuth bearer generation only for an explicitly approved legacy host/path contract; do not mix it with current static-key URLs.

Generation: Legacy core REST
Credential: OAuth bearer access token plus server-held client credential material
Transport: Authorization: Bearer header on the issued legacy endpoint generation
Evidence: 8 normalized operations · oauth2-bearer

Placement and restrictions

Allowed

Managed secret storage and a single-flight token provider
Trusted server SDK configured explicitly as oauth-bearer

Never place here

Client secret or bearer token in browsers, mobile apps, model prompts, source, build arguments, logs, or support packets
Legacy token with a current host/path, or a current key with legacy URLs

Restrict and prove

Exact legacy host/path and subscribed scope
Refresh before expiry with one concurrent owner and bounded failure
Migration owner, deadline, compatibility tests, and rollback evidence

Rotation and failure recovery

Rotate safely

Rotate client material in the provider-approved sequence
Warm and prove the new token provider without exposing token text
Drain the previous issuer material and complete the migration record

401 or authentication rejected

The credential generation, transport, host/path line, expiry, or product scope does not match the selected contract.

Stop retries; compare the issued credential class and exact contract, retain only a safe request identity, and test a new non-production credential after reconciliation.

403 or entitlement rejected

Authentication succeeded but the application, product, region, origin, package, bundle, asset, workspace, or operation is not allowed.

Keep the same credential shape and reconcile entitlement plus restrictions in the console; do not weaken restrictions blindly.

Works locally, fails in release

Release origin, signing certificate, bundle, egress address, build configuration, or environment injection differs from development.

Compare safe runtime identity to the registered restriction and prove the release artifact without printing the credential.

Explicit legacy mode · typescript

const mappls = new MapplsClient({
  tokenProvider: singleFlightOAuthProvider(secretStore),
  coreAuthentication: "oauth-bearer",
  // Endpoint overrides come only from the approved legacy contract.
});

Trusted secretTrusted Server

InTouch telematics data plane

Use a separately scoped InTouch bearer in a trusted data-plane adapter; never reuse the current core static key.

Generation: InTouch REST
Credential: Time-bound InTouch bearer
Transport: Authorization: Bearer header
Evidence: 53 normalized operations · bearer

Placement and restrictions

Allowed

Trusted server or MCP live-read process under a separately named secret
Short-lived internal result cache with tenant and policy identity

Never place here

APK, IPA, browser bundle, widget URL, client-side storage, model context, or a core-location credential variable
Unbounded asset history or arbitrary project proxy

Restrict and prove

Project, asset, operation, time range, user purpose, and data minimization
Precise-location access audit and response-field allow-list
Independent expiry, rotation, and incident response from core location credentials

Rotation and failure recovery

Rotate safely

Acquire a replacement through the approved InTouch project flow
Prove both token classification and least-scope reads in non-production
Drain, revoke, and reconcile independently of all core credentials

401 or authentication rejected

The credential generation, transport, host/path line, expiry, or product scope does not match the selected contract.

Stop retries; compare the issued credential class and exact contract, retain only a safe request identity, and test a new non-production credential after reconciliation.

403 or entitlement rejected

Authentication succeeded but the application, product, region, origin, package, bundle, asset, workspace, or operation is not allowed.

Keep the same credential shape and reconcile entitlement plus restrictions in the console; do not weaken restrictions blindly.

Works locally, fails in release

Release origin, signing certificate, bundle, egress address, build configuration, or environment injection differs from development.

Compare safe runtime identity to the registered restriction and prove the release artifact without printing the credential.

Separate InTouch provider · typescript

const mappls = new MapplsClient({
  tokenProvider: envToken("MAPPLS_STATIC_KEY"),
  coreAuthentication: "static-query",
  intouchTokenProvider: envToken("MAPPLS_INTOUCH_ACCESS_TOKEN"),
});

const status = await mappls.assetStatus({ assetId, region: "IND" });

Selection requiredTrusted Server

Workmate workforce APIs

Use the exact organization, actor, host, OAuth generation, and transition contract issued for the Workmate integration.

Generation: Workmate source generation
Credential: Organization/user-scoped OAuth evidence; issuance confirmation required
Transport: Bearer transport where declared by the selected source contract
Evidence: 13 normalized operations · oauth2-bearer

Placement and restrictions

Allowed

Trusted workforce integration service
User session only after company identity and Workmate actor mapping are approved

Never place here

Shared organization credential in a worker client
Treating a successful token as permission for every task transition

Restrict and prove

Organization, actor, task/action, purpose, region, and least fields
Optimistic concurrency, transition invariants, audit, outbox, and reconciliation
Exact source generation and provider provisioning approval

Rotation and failure recovery

Rotate safely

Freeze the exact actor/service mapping
Rotate through an approved non-production transition suite
Drain pending commands and reconcile unknown outcomes before revocation

401 or authentication rejected

The credential generation, transport, host/path line, expiry, or product scope does not match the selected contract.

Stop retries; compare the issued credential class and exact contract, retain only a safe request identity, and test a new non-production credential after reconciliation.

403 or entitlement rejected

Authentication succeeded but the application, product, region, origin, package, bundle, asset, workspace, or operation is not allowed.

Keep the same credential shape and reconcile entitlement plus restrictions in the console; do not weaken restrictions blindly.

Works locally, fails in release

Release origin, signing certificate, bundle, egress address, build configuration, or environment injection differs from development.

Compare safe runtime identity to the registered restriction and prove the release artifact without printing the credential.

Public + restrictedBrowser

Browser Web Maps and Places

Use only the browser-supported public credential class, restricted to exact origins; privileged REST operations stay behind a backend.

Generation: Selected Web SDK generation
Credential: Origin-restricted browser public key
Transport: Documented Web SDK configuration for the selected source line
Evidence: Non-REST or selection boundary

Placement and restrictions

Allowed

Documented Web SDK configuration or server-rendered public runtime configuration
Exact-origin development and production applications with separate keys

Never place here

Server secret, OAuth client secret, InTouch bearer, or unrestricted key in JavaScript
Secrets disguised by environment-variable names in a client build

Restrict and prove

Exact scheme, hostname, and port; avoid broad wildcards
CSP, dependency/version pinning, callback validation, and teardown
Separate preview, development, and production identities

Rotation and failure recovery

Rotate safely

Register new exact origins before rollout
Deploy the replacement public key and prove every origin
Remove the old key after cache/service-worker drain

401 or authentication rejected

The credential generation, transport, host/path line, expiry, or product scope does not match the selected contract.

Stop retries; compare the issued credential class and exact contract, retain only a safe request identity, and test a new non-production credential after reconciliation.

403 or entitlement rejected

Authentication succeeded but the application, product, region, origin, package, bundle, asset, workspace, or operation is not allowed.

Keep the same credential shape and reconcile entitlement plus restrictions in the console; do not weaken restrictions blindly.

Works locally, fails in release

Release origin, signing certificate, bundle, egress address, build configuration, or environment injection differs from development.

Compare safe runtime identity to the registered restriction and prove the release artifact without printing the credential.

Public runtime configuration · typescript

type PublicMapConfig = { publicKey: string; allowedOrigin: string };

const config = readPublicConfig();
if (location.origin !== config.allowedOrigin) throw new Error("Unexpected origin");
// Pass only the issued browser public key to the documented Web SDK adapter.

Public + restrictedAndroid

Android native application

Use only the Android app credential documented for the selected SDK line and restrict it to package plus signing identity.

Generation: Selected Android SDK generation
Credential: Android application public credential
Transport: Documented Android application initialization
Evidence: Non-REST or selection boundary

Placement and restrictions

Allowed

Documented Android manifest/resource/runtime configuration for a public app key
Variant-specific non-production and production configuration

Never place here

Static server key, OAuth client secret, or InTouch data-plane bearer in resources, BuildConfig, assets, native libraries, or Java/Kotlin
One fleet-wide secret baked into an APK

Restrict and prove

Exact package and signing certificate identity
SDK and toolchain compatibility plus release signing
Permission denial, recreation, background/resume, offline, and teardown tests

Rotation and failure recovery

Rotate safely

Register the next key against every active signing identity
Ship a bounded release cohort and monitor safe initialization errors
Retire the prior key only after supported app versions drain or an overlap policy is approved

401 or authentication rejected

The credential generation, transport, host/path line, expiry, or product scope does not match the selected contract.

Stop retries; compare the issued credential class and exact contract, retain only a safe request identity, and test a new non-production credential after reconciliation.

403 or entitlement rejected

Authentication succeeded but the application, product, region, origin, package, bundle, asset, workspace, or operation is not allowed.

Keep the same credential shape and reconcile entitlement plus restrictions in the console; do not weaken restrictions blindly.

Works locally, fails in release

Release origin, signing certificate, bundle, egress address, build configuration, or environment injection differs from development.

Compare safe runtime identity to the registered restriction and prove the release artifact without printing the credential.

Application-owned boundary · kotlin

interface MapCredentialProvider {
  fun publicAndroidKey(): String
}

// Inject only the package/signing-restricted app credential into the
// documented SDK initialization for the approved release line.

Public + restrictedIos

iOS native application

Use only the iOS app credential documented for the selected SDK release and bind approval to bundle/team context.

Generation: Selected iOS SDK generation
Credential: iOS application public credential
Transport: Documented iOS application initialization
Evidence: Non-REST or selection boundary

Placement and restrictions

Allowed

Documented iOS public app configuration for the selected package line
Target-specific non-production and production configuration

Never place here

Server key, OAuth client secret, or provider bearer in plist, source, resources, keychain-as-distribution, or binary obfuscation
Assuming Keychain makes an embedded provider secret safe

Restrict and prove

Exact bundle/team context and approved targets
Complete Swift/Xcode/package/binary compatibility set
Scene restore, backgrounding, memory pressure, permission changes, and teardown

Rotation and failure recovery

Rotate safely

Approve a replacement for every shipping target
Release with bounded overlap and safe initialization telemetry
Retire only after supported installed versions are accounted for

401 or authentication rejected

The credential generation, transport, host/path line, expiry, or product scope does not match the selected contract.

Stop retries; compare the issued credential class and exact contract, retain only a safe request identity, and test a new non-production credential after reconciliation.

403 or entitlement rejected

Authentication succeeded but the application, product, region, origin, package, bundle, asset, workspace, or operation is not allowed.

Keep the same credential shape and reconcile entitlement plus restrictions in the console; do not weaken restrictions blindly.

Works locally, fails in release

Release origin, signing certificate, bundle, egress address, build configuration, or environment injection differs from development.

Compare safe runtime identity to the registered restriction and prove the release artifact without printing the credential.

Application-owned boundary · swift

protocol MapCredentialProviding {
  var publicIOSKey: String { get }
}

// Supply only the bundle/team-approved public app credential to the
// documented SDK initializer for the resolved package set.

Selection requiredCross Platform

React Native, Flutter, Cordova, or Xamarin

Configure Android and iOS halves independently; shared JavaScript or Dart is neither a secret store nor evidence of native parity.

Generation: Wrapper plus underlying native SDK generations
Credential: Separate platform app credentials; wrapper-specific confirmation required
Transport: Underlying native initialization, not a shared privileged credential
Evidence: Non-REST or selection boundary

Placement and restrictions

Allowed

Android and iOS public application configuration separately
A typed bridge that never returns credential text to the shared layer

Never place here

Server secret in JavaScript, Dart, assets, compile-time constants, or a native bridge getter
One cross-platform key assumed to cover both native restriction systems

Restrict and prove

Android package/signing and iOS bundle/team independently
Wrapper/native dependency parity and release builds
Mount/unmount, late callbacks, offline, background/resume, and bridge cleanup

Rotation and failure recovery

Rotate safely

Rotate each native platform as its installed-base policy permits
Prove both release artifacts and shared error normalization
Retire per-platform versions independently

401 or authentication rejected

The credential generation, transport, host/path line, expiry, or product scope does not match the selected contract.

Stop retries; compare the issued credential class and exact contract, retain only a safe request identity, and test a new non-production credential after reconciliation.

403 or entitlement rejected

Authentication succeeded but the application, product, region, origin, package, bundle, asset, workspace, or operation is not allowed.

Keep the same credential shape and reconcile entitlement plus restrictions in the console; do not weaken restrictions blindly.

Works locally, fails in release

Release origin, signing certificate, bundle, egress address, build configuration, or environment injection differs from development.

Compare safe runtime identity to the registered restriction and prove the release artifact without printing the credential.

No credential bridge · typescript

type NativeMapAdapter = {
  ready(): Promise<void>;
  selectPlace(id: string): Promise<void>;
  dispose(): Promise<void>;
};

// The shared API exposes behavior—not Android/iOS credential values.

Entitlement-specificWidget

App widgets and iframe embeds

Many documented app widgets are credential-free; optional or paid access remains a literal placeholder until the exact widget entitlement is issued.

Generation: Selected widget contract
Credential: None, origin-restricted browser value, or paid ephemeral token—selection required
Transport: Documented iframe parameter or browser wrapper only where the selected widget requires it
Evidence: Non-REST or selection boundary

Placement and restrictions

Allowed

No credential for credential-free widget shapes
Only the documented browser-visible placeholder/value for an entitled widget
Exact-origin postMessage validation and narrow CSP

Never place here

Server secret in an iframe URL
Persisting or logging token-bearing URLs
Treating HTTP 200 or frame load as entitlement, coverage, publication, or business completion

Restrict and prove

Exact frame and message origins, schema, CSP, referrer policy, and fallback
Widget-specific entitlement, expiry, data purpose, and callback lifecycle
No sensitive payload in query parameters

Rotation and failure recovery

Rotate safely

Rotate only through the selected widget entitlement contract
Update the host without logging complete URLs
Prove expired/revoked/blocked behavior and remove cached token-bearing state

401 or authentication rejected

The credential generation, transport, host/path line, expiry, or product scope does not match the selected contract.

Stop retries; compare the issued credential class and exact contract, retain only a safe request identity, and test a new non-production credential after reconciliation.

403 or entitlement rejected

Authentication succeeded but the application, product, region, origin, package, bundle, asset, workspace, or operation is not allowed.

Keep the same credential shape and reconcile entitlement plus restrictions in the console; do not weaken restrictions blindly.

Works locally, fails in release

Release origin, signing certificate, bundle, egress address, build configuration, or environment injection differs from development.

Compare safe runtime identity to the registered restriction and prove the release artifact without printing the credential.

Credential-free host first · html

<iframe
  src="APPROVED_MAPPLS_WIDGET_URL"
  title="Mappls place experience"
  referrerpolicy="no-referrer"
></iframe>
<!-- Never paste a server credential into an iframe URL. -->

No credentialDeep Link

Mappls deep links

Mappls app hand-off links need no credential; the URL carries only bounded, non-sensitive intent.

Generation: Current documented link shape
Credential: No credential
Transport: Validated HTTPS link, with installed-app URI only where documented
Evidence: Non-REST or selection boundary

Placement and restrictions

Allowed

Validated public intent with encoded Mappls Pin, coordinates, name, or travel mode as documented

Never place here

Any API key, token, private address, precise private/user payload, internal ID, or server secret in the URL
Assuming click means app-open or arrival

Restrict and prove

Allow-listed HTTPS host/path and bounded fields
Consent before sending location intent
Separate click, app open, browser fallback, recovery, and arrival evidence

Rotation and failure recovery

Rotate safely

No credential rotation
Version and regression-test the approved link shape
Remove deprecated paths through normal application release control

The app does not open

The URI is undocumented, unavailable, or the app is not installed.

Use the documented HTTPS link as the primary hand-off and retain a visible browser fallback.

The destination is wrong

Coordinate order, encoding, Mappls Pin, or mode differs from the selected intent contract.

Rebuild through the bounded deep-link tool and test the same fixture across app-installed and browser-only devices.

Intent only · typescript

const url = buildMapplsDeepLink({
  intent: "share-place",
  mapplsPin: selectedPlace.mapplsPin,
});
// Never append a key, token, or private application payload.

Entitlement-specificEnterprise

mGIS browser surfaces

Keep the entitled widget key, Web JS access token, durable workspace API identity, and sovereign deployment identity as separate contracts.

Generation: Selected mGIS or MIGIST surface
Credential: Surface-specific enterprise credential; exact issuance required
Transport: Documented browser parameter or approved trusted adapter for the selected surface
Evidence: Non-REST or selection boundary

Placement and restrictions

Allowed

Browser-visible widget/Web SDK value only where explicitly documented and origin-restricted
Trusted adapter for workspace/API credentials
Deployment-specific device/workload identity for sovereign runtimes

Never place here

Server/workspace secret in browser code
Reusing an mGIS browser value for MIGIST, generic REST, or another tenant
Invented endpoint or method name where source evidence conflicts

Restrict and prove

Tenant, workspace, dataset, method, role, share/export purpose, origin, and retention
Versioned dataset/style/workview identity and immutable lineage
Exact entitlement plus naming-drift release gates

Rotation and failure recovery

Rotate safely

Classify every consumer by surface before issuance
Rotate browser and trusted-service identities independently
Reconcile in-flight analysis/export attempts before revoking a service identity

401 or authentication rejected

The credential generation, transport, host/path line, expiry, or product scope does not match the selected contract.

Stop retries; compare the issued credential class and exact contract, retain only a safe request identity, and test a new non-production credential after reconciliation.

403 or entitlement rejected

Authentication succeeded but the application, product, region, origin, package, bundle, asset, workspace, or operation is not allowed.

Keep the same credential shape and reconcile entitlement plus restrictions in the console; do not weaken restrictions blindly.

Works locally, fails in release

Release origin, signing certificate, bundle, egress address, build configuration, or environment injection differs from development.

Compare safe runtime identity to the registered restriction and prove the release artifact without printing the credential.

Trusted workspace seam · typescript

interface MgisWorkspaceAdapter {
  publish(command: PublishDatasetCommand): Promise<ProviderReceipt>;
  reconcile(attemptId: string): Promise<AttemptStatus>;
}
// Exact endpoint and auth come only from the approved workspace contract.

Entitlement-specificDevice

Offline and automotive activation

Treat per-device activation, licensed runtime/data, signatures, and fleet release policy as a provisioning system—not as a reusable API key.

Generation: Entitled runtime and data release
Credential: Per-device/workload identity plus non-secret activation evidence and licensed artifacts
Transport: Approved manufacture/fleet provisioning channel
Evidence: Non-REST or selection boundary

Placement and restrictions

Allowed

Per-device secure hardware/workload identity
Signed manifests and separately delivered runtime/data/license material
Non-secret activation state in health evidence

Never place here

Fleet-wide shared secret or license baked into an image
Protected artifact bodies, package URLs, keys, or license files in docs, logs, model context, or support bundles
Treating copied files as successful activation

Restrict and prove

Device, fleet, region, hardware/software manifest, validity, and release cohort
Signature, compatibility, storage, power-loss, rollback, backup/restore, and retirement
Minimum offline privilege and revocation/reconciliation on reconnect

Rotation and failure recovery

Rotate safely

Stage a signed compatible release in the inactive slot
Qualify, atomically activate, observe, and retain rollback
Retire the previous release or device identity only after fleet reconciliation

Runtime starts but rendering or routing fails

Runtime, data epoch, ABI, graphics, configuration, voice, region, or activation is incompatible.

Fail readiness, retain the prior slot, compare the signed release manifest to device facts, and obtain the exact compatibility decision.

Activation is unknown after interruption

The process persisted partial files instead of one atomic active-slot pointer and durable receipt.

Boot the last qualified slot, reconcile the staged manifest and activation journal, and never guess success from file presence.

Fleet lifecycle · text

manufacture → provision → stage → qualify → activate → observe
                                      ↘ rollback → reconcile → retire

No shared fleet credential belongs in the runtime image.

Selection requiredMcp

MCP and AI-native clients

Keep MCP client identity, tool authorization, and underlying Mappls provider credentials as independent security planes.

Generation: MCP offline or live-read profile
Credential: None for offline tools; gateway/OAuth client token for remote MCP; product credential stays inside the server for approved live reads
Transport: Local stdio or authenticated stateless Streamable HTTP; provider transport is tool-specific and never exposed to the client
Evidence: 162 normalized operations · bearer / not-declared / oauth2-bearer

Placement and restrictions

Allowed

Provider credentials only in the MCP service secret provider
Short-lived remote MCP access token only in the MCP client transport
No credential for local/offline catalog tools

Never place here

Provider key/token in model context, prompt, tool arguments, client configuration, structured output, errors, logs, or provenance
MCP gateway token reused as a Mappls provider credential
Write tools or arbitrary URLs in the read-only profile

Restrict and prove

Exact MCP resource, issuer, audience, principal, client, scope, expiry, origin, and profile
Tool allow-list, input/output bounds, egress allow-list, redaction, rate limit, audit, and approval
Underlying product credential restricted independently by product, region, and server egress

Rotation and failure recovery

Rotate safely

Rotate MCP gateway/OAuth identity independently of provider credentials
Rotate each provider credential through its own path while keeping tool schemas stable
Revoke leases and reconcile in-flight executions before removing either identity

401 or authentication rejected

The credential generation, transport, host/path line, expiry, or product scope does not match the selected contract.

Stop retries; compare the issued credential class and exact contract, retain only a safe request identity, and test a new non-production credential after reconciliation.

403 or entitlement rejected

Authentication succeeded but the application, product, region, origin, package, bundle, asset, workspace, or operation is not allowed.

Keep the same credential shape and reconcile entitlement plus restrictions in the console; do not weaken restrictions blindly.

Works locally, fails in release

Release origin, signing certificate, bundle, egress address, build configuration, or environment injection differs from development.

Compare safe runtime identity to the registered restriction and prove the release artifact without printing the credential.

Tool is not listed

The endpoint uses the offline profile, the client lacks the required scope, or the selected capability is intentionally unavailable.

Use offline planning first; move to a separately deployed live-read profile only with approved product entitlement and least scope.

Remote MCP client boundary · json

{
  "url": "https://mcp.example.com/mcp",
  "headers": { "Authorization": "Bearer ${MCP_RESOURCE_TOKEN}" }
}
// MAPPLS_* provider credentials exist only in the MCP server process.

Selection requiredEnterprise

Entitled or source-ambiguous product

When public evidence does not establish issuance, host/path generation, or client placement, stop at the adapter boundary and obtain the exact account contract.

Generation: Account-specific
Credential: Selection required
Transport: Selection required—never inferred from an adjacent Mappls product
Evidence: Non-REST or selection boundary

Placement and restrictions

Allowed

Typed adapter with no credential literal
Blank secret/public-key placeholders classified by intended runtime
Provisioning request that records exact evidence gaps

Never place here

Trying static key, OAuth bearer, browser token, or another product credential until one works
Copying a sample credential field into production without matching issuance and restriction evidence

Restrict and prove

Provider owner, product, generation, host/path, runtime, transport, scopes, region, restriction, expiry, rotation, and revocation must all be answered
Non-production hostile-path proof before production issuance

Rotation and failure recovery

Rotate safely

Define the issued lifecycle before the first credential
Prove replacement, overlap/drain, revoke, and reconciliation in non-production
Attach evidence to the application—not to informal operator memory

401 or authentication rejected

The credential generation, transport, host/path line, expiry, or product scope does not match the selected contract.

Stop retries; compare the issued credential class and exact contract, retain only a safe request identity, and test a new non-production credential after reconciliation.

403 or entitlement rejected

Authentication succeeded but the application, product, region, origin, package, bundle, asset, workspace, or operation is not allowed.

Keep the same credential shape and reconcile entitlement plus restrictions in the console; do not weaken restrictions blindly.

Works locally, fails in release

Release origin, signing certificate, bundle, egress address, build configuration, or environment injection differs from development.

Compare safe runtime identity to the registered restriction and prove the release artifact without printing the credential.

Fail-closed adapter · typescript

interface EntitledProviderAdapter {
  execute(command: ApprovedCommand): Promise<ProviderReceipt>;
}

throw new Error("Credential contract selection required");

Release rules

Five controls every integration keeps.

A credential name is not an authentication contract: product, runtime, generation, host/path, transport, region, restriction, expiry, and owner must agree.
Public browser/mobile keys are observable and therefore rely on exact restrictions; server keys, client secrets, and provider bearers never enter untrusted clients.
Current core static-query, legacy core OAuth, InTouch bearer, widget values, device activation, and MCP client identity are separate generations and security planes.
Repository security signals and normalized contracts are evidence, not proof of account entitlement, supported versions, or universal issuance behavior.
Rotation is a measured overlap-and-drain journey; revocation without consumer and in-flight reconciliation creates unknown outcomes.