AuthorizationConfig¶

public classAuthorizationConfig

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.

let bgGeo = BGGeo.shared
let token = "my-auth-token"
let refreshToken = "my-refresh-token"

// Listen for authorization refresh results
let sub = bgGeo.onAuthorization { event in
    if event.isSuccess {
        print("[authorization] SUCCESS:", event.response)
    } else {
        print("[authorization] ERROR:", event.error ?? "")
    }
}

// Initialize with JWT authorization
bgGeo.ready { config in
    config.http.url = "https://app.your.server.com/users/locations"
    config.http.autoSync = true
    config.authorization.strategy = "JWT"
    config.authorization.accessToken = token
    config.authorization.refreshToken = refreshToken
    config.authorization.refreshUrl = "https://auth.your.server.com/tokens"
    config.authorization.refreshPayload = [
        "the_refresh_token_field_name": "{refreshToken}"
    ]
    config.authorization.expires = -1
}

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 BGGeo.onAuthorization with an AuthorizationEvent.

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

let bgGeo = BGGeo.shared
bgGeo.onAuthorization { event in
    if event.isSuccess {
        print("[authorization] SUCCESS:", event.response)
    } else {
        print("[authorization] ERROR:", event.error ?? "")
    }
}

Members¶

accessToken¶

public var accessToken: String?

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.

expires¶

public var expires: TimeInterval

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¶

public var refreshHeaders: [String: String]?

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 {}.

let bgGeo = BGGeo.shared
bgGeo.ready { config in
    config.authorization.accessToken = "XXX.YYY.ZZZ"
    config.authorization.refreshUrl = "https://auth.domain.com/tokens"
    config.authorization.refreshToken = "smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb"
    config.authorization.refreshPayload = [
        "my_refresh_token": "{refreshToken}",
        "grant_type": "refresh_token",
        "foo": "another arbitrary field"
    ]
    config.authorization.refreshHeaders = [:]  // Empty dict to provide no refreshHeaders.
}

refreshPayload¶

public var refreshPayload: [String: Any]?

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.

let bgGeo = BGGeo.shared
bgGeo.ready { config in
    config.authorization.strategy = "JWT"
    config.authorization.accessToken = "XXX.YYY.ZZZ"
    config.authorization.refreshUrl = "https://auth.your.server.com/tokens"
    config.authorization.refreshToken = "smTsfaspfgaadsfgqZerUt0wueflasdfkaxjdfeKIacb"
    config.authorization.refreshPayload = [
        "my_refresh_token": "{refreshToken}",
        "grant_type": "refresh_token",
        "foo": "another arbitrary field"
    ]
}

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¶

public var refreshToken: String?

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¶

public var refreshUrl: String?

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 BGGeo.onAuthorization with an AuthorizationEvent.

strategy¶

public var strategy:AuthorizationStrategy?

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).