AuthorizationConfig¶

class Authorization

Token-based authorization configuration for the background geolocation SDK.

AuthorizationConfig enables the SDK to authenticate HTTP uploads with an access token and to automatically refresh that token when it expires or when the server returns 401 Unauthorized.

When using Config.authorization, do not set Authorization manually inside HttpConfig.headers — the SDK manages the authorization header automatically.

Overview¶

The SDK attaches the configured access token to every HTTP upload request as an Authorization header. If you supply AuthorizationConfig.refreshUrl, AuthorizationConfig.refreshToken, and AuthorizationConfig.refreshPayload, the SDK can automatically refresh expired tokens when a 401 Unauthorized response is received.

Category	Properties	Notes
Token	`strategy`, `accessToken`, `expires`	Token value and expiry.
Refresh	`refreshUrl`, `refreshToken`, `refreshPayload`, `refreshHeaders`	Auto-refresh on `401` or expiry.

BackgroundGeolocation.onAuthorization((AuthorizationEvent event) {
  if (event.success) {
    print('[authorization] SUCCESS: ${event.response}');
  } else {
    print('[authorization] ERROR: ${event.error}');
  }
});

BackgroundGeolocation.ready(Config(
  http: HttpConfig(
    url: "https://app.your.server.com/users/locations",
    autoSync: true,
  ),
  authorization: Authorization(
    strategy: "JWT",
    accessToken: "my-access-token",
    refreshToken: "my-refresh-token",
    refreshUrl: "https://auth.your.server.com/tokens",
    refreshPayload: {
      'the_refresh_token_field_name': "{refreshToken}"
    },
  )
));

Token refresh¶

When a 401 Unauthorized response is received, or when expires is reached, the SDK sends an application/x-www-form-urlencoded POST to refreshUrl with the refreshPayload fields encoded in the body.

On receiving the response, the SDK recursively iterates through the JSON keys to locate:

A new access token
A new refresh token (if present)
An expiry time (if present)

The SDK recognizes a wide variety of response shapes automatically. For example, a nested response:

{
  "token": {
    "access_token": "XXX.YYY.ZZZ",
    "expires_at": 3900
  },
  "refresh_token": "smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb"
}

And a flat response:

{
  "accessToken": "XXX.YYY.ZZZ",
  "refreshToken": "smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb",
  "expiry": 3900
}

Both are handled automatically.

Refresh payload¶

refreshPayload is a key/value map sent as form fields in the refresh POST. At least one field must use the template variable "{refreshToken}", which the SDK replaces with the current refreshToken value at request time. Additional arbitrary fields required by your authorization server may also be included.

If refreshHeaders is not set, the SDK automatically injects Authorization: Bearer {accessToken} into each refresh request. Pass an empty object {} to send no headers with the refresh request.

Authorization events¶

Whenever the SDK receives a response from refreshUrl, it fires BackgroundGeolocation.onAuthorization with an AuthorizationEvent.

On success, AuthorizationEvent.response contains the parsed JSON from the refresh server.
On error, AuthorizationEvent.error contains the error message.

BackgroundGeolocation.onAuthorization((AuthorizationEvent event) {
  if (event.success) {
    print('[authorization] SUCCESS: ${event.response}');
  } else {
    print('[authorization] ERROR: ${event.error}');
  }
});

Members¶

accessToken¶

String? accessToken

The access token attached to each HTTP request as an Authorization header.

The SDK automatically applies the token to every upload request sent to HttpConfig.url. Do not set Authorization manually in HttpConfig.headers.

BackgroundGeolocation.ready(Config(
  authorization: Authorization(
    strategy: "JWT",
    accessToken: "XXX.YYY.ZZZ"
  )
));

expires¶

int? expires

Token expiry time in seconds since epoch. Defaults to -1 (not set).

When set, the SDK proactively refreshes the token before expiry rather than waiting for a 401 Unauthorized response. When not set (default -1), the SDK relies on a 401 response to trigger a refresh.

refreshHeaders¶

Map? refreshHeaders

HTTP headers sent with each request to refreshUrl.

If not set, the SDK automatically injects Authorization: Bearer {accessToken} into refresh requests, where {accessToken} is replaced with the current access token. To send no headers with refresh requests, provide an empty object {}.

refreshHeaders: const {}

refreshPayload¶

Map? refreshPayload

Form fields sent in the application/x-www-form-urlencoded POST to refreshUrl when requesting a new accessToken after expiration.

Include at least one field whose value is the template string "{refreshToken}". The SDK automatically replaces this with the configured refreshToken value before sending the request.

BackgroundGeolocation.ready(Config(
  authorization: Authorization(
    strategy: "JWT",
    accessToken: "XXX.YYY.ZZZ",
    refreshUrl: "https://auth.domain.com/tokens",
    refreshToken: "smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb",
    refreshPayload: {
      "grant_type": "refresh_token",
      "refresh_token": "{refreshToken}",   // <-- will be replaced with the configured refreshToken
      "rememberMe": "true"                 // <-- non-strings must be stringified
    }
  )
));

The equivalent curl representation of the SDK's form POST:

$ curl -X POST \
  -F 'my_refresh_token=smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb' \
  -F 'grant_type=refresh_token' \
  -F 'foo=another arbitrary field' \
  https://auth.your.server.com/tokens

refreshToken¶

String? refreshToken

The token sent to refreshUrl when a new accessToken is needed after expires or when HTTP 401 Unauthorized is received.

The SDK encodes this value into the refreshPayload by substituting the "{refreshToken}" template variable before sending the refresh request.

refreshUrl¶

String? refreshUrl

The URL of the authorization server that provides a new accessToken when the current token expires.

The SDK POSTs to this URL using application/x-www-form-urlencoded when the current token expires or when the location server returns 401 Unauthorized. The response is parsed automatically — see Token refresh for supported response formats.

When the SDK receives a response from the server, it fires BackgroundGeolocation.onAuthorization with an AuthorizationEvent.

strategy¶

String? strategy

Authorization strategy used when attaching the token to HTTP requests. Defaults to "JWT".

"JWT" — sends the token as Authorization: Bearer <token>.
"SAS" — sends the token as Authorization: <token> (no Bearer prefix).