RelayClientProtocol

public protocol RelayClientProtocol : AnyObject, Sendable

Represents a client for the Relay API.

Use this struct to connect and authenticate with a Relay server, managing authorization to call protected endpoints.

# Authorization

  • Clients should use the [fxa_client::FirefoxAccount::getAccessToken()] function to obtain a relay-scoped access token (scope: https://identity.mozilla.com/apps/relay).
  • Then, construct the [RelayClient] with the access token. All requests will then be authenticated to the Relay server via Authorization: Bearer {fxa-access-token}.
  • The Relay server verifies this token with the FxA OAuth /verify endpoint.
  • Clients are responsible for getting a new access token when needed.

  • Creates a Relay user record in the Relay service database.

    This function was originally used to signal acceptance of terms and privacy notices, but now primarily serves to provision (create) the Relay user record if one does not exist.

    ## Errors

    • RelayApi: Returned for any non-successful (non-2xx) HTTP response. Provides the HTTP status and response body; downstream consumers can inspect these fields. If the response body is JSON with error_code or detail fields, these are parsed and included for more granular handling; otherwise, the raw response text is used as the error detail.
    • Network: Returned for transport-level failures, like loss of connectivity, with details in reason.
    • Other variants may be returned for unexpected deserialization, URL, or backend errors.

    Declaration

    Swift

    func acceptTerms() throws

  • Creates a new Relay mask (alias) with the specified metadata.

    This is used to generate a new alias for use in an email field.

    • description: A label shown in the Relay dashboard; defaults to generated_for, user-editable later.
    • generated_for: The website for which the address is generated.
    • used_on: Comma-separated list of all websites where this address is used. Only updated by some clients.

    ## Errors

    • RelayApi: Returned for any non-successful (non-2xx) HTTP response. Provides the HTTP status and response body; downstream consumers can inspect these fields. If the response body is JSON with error_code or detail fields, these are parsed and included for more granular handling; otherwise, the raw response text is used as the error detail.
    • Network: Returned for transport-level failures, like loss of connectivity, with details in reason.
    • Other variants may be returned for unexpected deserialization, URL, or backend errors.

    Declaration

    Swift

    func createAddress(description: String, generatedFor: String, usedOn: String) throws -> RelayAddress

  • Retrieves all Relay addresses associated with the current account.

    Returns a vector of [RelayAddress] objects on success.

    ## Errors

    • RelayApi: Returned for any non-successful (non-2xx) HTTP response. Provides the HTTP status and response body; downstream consumers can inspect these fields. If the response body is JSON with error_code or detail fields, these are parsed and included for more granular handling; otherwise, the raw response text is used as the error detail.
    • Network: Returned for transport-level failures, like loss of connectivity, with details in reason.
    • Other variants may be returned for unexpected deserialization, URL, or backend errors.

    Declaration

    Swift

    func fetchAddresses() throws -> [RelayAddress]