--- title: Authentication description: Carry credentials through file, tile, and service requests without coupling loaders.gl to a sign-in system. hide_title: true page_style: designed --- import {DocPageHeader} from '@site/src/components/docs/doc-page-header'; import {DocOrientation, ReferenceBoundary} from '@site/src/components/docs/designed-doc'; loaders.gl uses one credential pipeline for files, tiles, service metadata, and the follow-up requests made by a source. Applications provide a static token or an asynchronous token callback; loaders.gl decides where that credential may be sent and carries it through `load`, `createDataSource`, service runtimes, and deck.gl source layers. The pipeline deliberately does not implement sign-in screens, OAuth redirects, secure storage, or provider token issuance. Those remain application responsibilities. Its job begins when the application can return a usable token. ## Declarative credentials `core.credentials` can contain JSON configuration as well as existing credential objects. Supply constructors through `core.authentications`; each constructor's static `type` selects the matching configuration: ```ts import {MapboxAuthentication} from '@loaders.gl/services'; const loadOptions = { core: { authentications: [MapboxAuthentication], credentials: [{type: 'mapbox', accessToken: mapboxToken}] } }; ``` Available service classes are `ArcGISAuthentication` (`arcgis`, from `@loaders.gl/arcgis/authentication`), `MapboxAuthentication` (`mapbox`), `GoogleMapsAuthentication` (`google-maps`), and `CesiumIonAuthentication` (`cesium-ion`). They accept the same options as the corresponding `create*Credential` helpers. `@loaders.gl/core/loader-utils` also exports `BearerTokenAuthentication` (`bearer-token`) and `QueryParameterAuthentication` (`query-parameter`). There is no implicit global registry. Loaders may contribute constructors through `getAuthentications(url, options)`. ArcGIS service loaders supply `ArcGISAuthentication` automatically when used through `load` or `createDataSource`. Application constructors take precedence for the same type. Unknown types fail before the data request. Classes receive one credential entry, are instantiated once per load, and their instances are reused by nested requests. Existing credential instances remain valid and can be mixed with declarations. Direct source constructors require classes in options. For asynchronous discovery hooks, use `load` instead of synchronous `createDataSource`. ## Provider-specific response errors A provider's `RequestCredential` may implement `shouldRefresh(response)` to detect authentication failures encoded in response bodies. It must inspect a clone so the original response stays readable. The hook is consulted only for an applied callback token and a replayable request. `canReplayRequest(url, options)` can additionally permit a provider's read-only POST operation; it is checked against both original and signed requests. The shared transport still permits at most one refresh/replay. `TokenAuthentication` preserves these hooks. ArcGIS uses them for bounded JSON 498/499 error detection and form-encoded layer queries; other credentials retain their existing HTTP-status behavior. ## Application request signing For signing that depends on the individual URL, method, headers or body, supply a callback credential. loaders.gl does not import an AWS/S3 SDK; the application provides its signer: ```ts import type {RequestAuthentication} from '@loaders.gl/core/loader-utils'; // signRequest is application code. It returns the complete {url, options} to send. const credential: RequestAuthentication = { id: 'private-tiles', type: 'request', origins: ['s3://my-bucket', 'https://my-bucket.s3.us-east-1.amazonaws.com'], authenticate: async ({url, options, reason}) => { return signRequest({url, options, refresh: reason === 'retry'}); }, refreshStatusCodes: [401, 403] }; const loadOptions = {core: {credentials: [credential]}}; ``` The callback runs for every matching request, after static fetch defaults, per-request options, and ordinary token credentials have been applied. It can translate custom URLs to HTTPS, return a presigned URL, or sign headers. Preserve existing options such as range headers and body in the returned request. The caller's abort signal is retained automatically. Custom fetch implementations must send the signed fields without altering them. A callback is trusted application code and is responsible for handling explicitly signed input URLs and redacting provider-specific errors. Retries are opt-in, limited to one replay, and only allowed for replayable methods and bodies. Each replay is signed afresh from the original request; signatures are never reused between tiles. Provider credential refresh and refresh deduplication belong to the application signer. The same callback can be declared through JSON by supplying an application class: ```ts import type {AuthenticationRequest, RequestAuthentication} from '@loaders.gl/core/loader-utils'; class ApplicationSigningAuthentication implements RequestAuthentication { static readonly type = 'application-signing'; readonly type = 'request'; readonly id = 'private-tiles'; readonly origins: readonly string[]; constructor(readonly configuration: {origins: string[]; region: string}) { this.origins = configuration.origins; } authenticate(request: AuthenticationRequest) { return signRequest({...request, region: this.configuration.region}); } } const loadOptions = { core: { authentications: [ApplicationSigningAuthentication], credentials: [{ type: 'application-signing', origins: ['https://my-bucket.s3.us-east-1.amazonaws.com'], region: 'us-east-1' }] } }; ``` Constructor references and callbacks live in JavaScript; the credential configuration can live in JSON. Request callbacks and token-provider functions keep parsing on the calling thread so nested requests retain authentication. Static resolved token credentials can still use workers. S3 endpoint resolution and AWS signing remain application responsibilities. ## The minimal pattern ArcGIS presets live in `@loaders.gl/arcgis/authentication`; other provider presets live in `@loaders.gl/services`. Pass the resulting credential through `core.credentials`: ```ts import {createDataSource} from '@loaders.gl/core'; import {ArcGISFeatureServerLoader} from '@loaders.gl/arcgis'; import {createArcGISCredential} from '@loaders.gl/arcgis/authentication'; const credentials = [ createArcGISCredential({ origins: ['https://services.example.com'], token: arcgisToken }) ]; const source = await createDataSource(featureServerUrl, ArcGISFeatureServerLoader, { core: {credentials} }); const features = await source.getFeatures({layers: ['0']}); ``` The exact same option works with `createDataSource`, source-backed tile layers, and loaders that make nested requests. Explicit credentials already present on a request URL or in its headers take precedence over a configured credential. ## Static tokens and refreshing tokens A string is appropriate for a token whose lifetime exceeds the source. For expiring credentials, provide a callback that returns the current token and refreshes it when asked: ```ts import {createBearerTokenCredential} from '@loaders.gl/core/loader-utils'; let currentToken = await acquireToken(); const credential = createBearerTokenCredential({ id: 'private-tiles', origins: ['https://tiles.example.com'], token: async ({reason, response}) => { if (reason === 'refresh') { currentToken = await refreshToken({status: response?.status}); } return currentToken; } }); ``` Callbacks receive `reason: 'request'` for normal authorization and `reason: 'refresh'` after an accepted authentication failure. Refreshes for the same credential are deduplicated. loaders.gl replays at most once, and only for an idempotent request with a reusable body. Static tokens are never refreshed automatically. ## Provider presets | Provider | Helper | Placement | Default origin | Notes | | --- | --- | --- | --- | --- | | ArcGIS REST | `createArcGISCredential` | `token` query parameter | None; required | Includes ArcGIS 498 and 499 refresh statuses | | Mapbox | `createMapboxCredential` | `access_token` query parameter | `https://api.mapbox.com` | Suitable for TileJSON and child tile requests | | Google Maps Platform | `createGoogleMapsCredential` | `key` query parameter | `https://tile.googleapis.com` | A server-returned 3D Tiles `session` parameter is preserved separately | | Cesium ion REST API | `createCesiumIonCredential` | Bearer header | `https://api.cesium.com` | Authorizes ion discovery and endpoint bootstrap | Every helper accepts an async token callback. `origins` replaces a helper's default allowlist when the service is reached through a proxy or another provider host. ### Mapbox tiles ```ts import {createDataSource} from '@loaders.gl/core'; import {MVTLoader} from '@loaders.gl/tiles/mvt'; import {createMapboxCredential} from '@loaders.gl/services'; const source = await createDataSource(tileJSONUrl, [MVTLoader], { core: { credentials: [createMapboxCredential({accessToken: mapboxToken})] } }); ``` ### Google 3D Tiles ```ts import {Tiles3DLoader} from '@loaders.gl/tiles-3d/3d-tiles'; import {Tiles3DSource} from '@loaders.gl/tiles-3d'; import {createGoogleMapsCredential} from '@loaders.gl/services'; const source = new Tiles3DSource( {url: googleTilesetUrl, loader: Tiles3DLoader}, {core: {credentials: [createGoogleMapsCredential({apiKey: googleApiKey})]}} ); ``` Google's API key authorizes the request. The `session` query parameter returned in tileset content URLs is request state, not another application credential; `Tiles3DSource` preserves both values without replacing an explicit child parameter. ### Cesium ion ```ts import {load} from '@loaders.gl/core'; import {resolveCesiumIonTileset, Tiles3DLoader} from '@loaders.gl/tiles-3d/3d-tiles'; const endpoint = await resolveCesiumIonTileset(accessToken, 123); const tileset = await load(endpoint.url, Tiles3DLoader, { core: {credentials: endpoint.credentials} }); ``` The resolver sends the account token only to `api.cesium.com`. The returned credentials scope the endpoint token to the resolved origin and refresh it when the server rejects it. Pass the credentials to the tileset consumer so child requests can authenticate. ## I3S and deck.gl layers Pass credentials inside the usual `loadOptions`. The source-backed adapters retain them for I3S metadata, node pages, geometry, textures, attributes, and other dependent resources: ```ts import {I3SLoader} from '@loaders.gl/tiles-3d/i3s'; import {SourceLayer} from '@loaders.gl/deck-layers'; const layer = new SourceLayer({ id: 'secured-i3s', data: i3sLayerUrl, loaders: [I3SLoader], loadOptions: {core: {credentials}} }); ``` For a `Tile3DSourceLayer`, pass the same `core.credentials` object in `loadOptions`. The older `@deck.gl/geo-layers` `Tile3DLayer` path remains compatible with the legacy `i3s.token` option; when using that path, put the token on the initial URL as well because the initial request occurs before the I3S parser receives its options. ## Security model - Credentials are sent only when `URL.origin` exactly matches an allowlisted origin. Paths and wildcard subdomains are intentionally unsupported. - Use separate credentials when APIs and asset hosts have different trust boundaries. - Credential query parameters are redacted from `ServiceRuntime` telemetry and normalized request errors. Applications should apply the same policy to custom fetch logging. - Prefer headers when the provider supports them: query parameters can appear in browser history, intermediary logs, and copied URLs. - loaders.gl keeps tokens in memory only through the values and callbacks supplied by the application. It does not persist them. ## Cookies, proxies, and custom transports Cookie-authenticated services still use standard fetch configuration: ```ts const source = createDataSourceSync(url, loaders, { core: {fetch: {credentials: 'include'}} }); ``` The server must permit the browser origin and credentials through CORS. For signed URLs, complex request signing, service workers, or application gateways, provide `core.fetch`; the common credential wrapper composes with that function. Avoid configuring both a custom signer and a loaders.gl credential for the same field unless explicit request values are intended to win. See the [request credential API](/docs/modules/core/loader-utils/api-reference/request-credentials) for the generic constructors and callback contract.