ARTAuthOptions

Objective-C

@interface ARTAuthOptions : NSObject <NSCopying>

Swift

class ARTAuthOptions : NSObject, NSCopying

Passes authentication-specific properties in authentication requests to Ably. Properties set using ARTAuthOptions are used instead of the default values set when the client library is instantiated, as opposed to being merged with them.

  • key

    The full API key string, as obtained from the Ably dashboard. Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably ARTTokenRequests. Read more about Basic authentication.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) NSString *key;

    Swift

    var key: String? { get set }

  • An authenticated token. This is a token string obtained from the ARTTokenDetails.token property of an ARTTokenDetails component of an Ably ARTTokenRequest response, or a JSON Web Token satisfying the Ably requirements for JWTs. This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that enables the client library to renew the token automatically when the previous one expires, such as authUrl or authCallback. Read more about Token authentication.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) NSString *token;

    Swift

    var token: String? { get set }

  • An authenticated ARTTokenDetails object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that enables the client library to renew the token automatically when the previous one expires, such as authUrl or authCallback. Use this option if you wish to use Token authentication. Read more about Token authentication.

    Declaration

    Objective-C

    @property (nonatomic, nullable) ARTTokenDetails *tokenDetails;

    Swift

    var tokenDetails: ARTTokenDetails? { get set }

  • Called when a new token is required. The role of the callback is to obtain a fresh token, one of: an Ably Token string (in plain text format); a signed ARTTokenRequest; a ARTTokenDetails (in JSON format); an Ably JWT. See the authentication documentation for details of the Ably ARTTokenRequest format and associated API calls.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) ARTAuthCallback authCallback;

    Swift

    var authCallback: ARTAuthCallback? { get set }

  • A URL that the library may use to obtain a token string (in plain text format), or a signed ARTTokenRequest or ARTTokenDetails (in JSON format) from.

    Declaration

    Objective-C

    @property (nonatomic, nullable) NSURL *authUrl;

    Swift

    var authUrl: URL? { get set }

  • The HTTP verb to use for any request made to the authUrl, either GET or POST. The default value is GET.

    Declaration

    Objective-C

    @property (nonatomic, copy, null_resettable) NSString *authMethod;

    Swift

    var authMethod: String! { get set }

  • A set of key-value pair headers to be added to any request made to the authUrl. Useful when an application requires these to be added to validate the request or implement the response. If the authHeaders object contains an “authorization” key, then “withCredentials” is set on the XHR request.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) NSStringDictionary *authHeaders;

    Swift

    var authHeaders: [String : String]? { get set }

  • A set of key-value pair params to be added to any request made to the authUrl. When the authMethod is GET, query params are added to the URL, whereas when authMethod is POST, the params are sent as URL encoded form data. Useful when an application requires these to be added to validate the request or implement the response.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) NSArray<NSURLQueryItem *> *authParams;

    Swift

    var authParams: [URLQueryItem]? { get set }

  • If true, the library queries the Ably servers for the current time when issuing ARTTokenRequests instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably ARTTokenRequests, so this option is useful for library instances on auth servers where for some reason the server clock cannot be kept synchronized through normal means, such as an NTP daemon. The server is queried for the current time once per client library instance (which stores the offset from the local clock), so if using this option you should avoid instancing a new version of the library for each request. The default is false.

    Declaration

    Objective-C

    @property (nonatomic) BOOL queryTime;

    Swift

    var queryTime: Bool { get set }

  • When true, forces token authentication to be used by the library. If a clientId is not specified in the ARTClientOptions or ARTTokenParams, then the Ably Token issued is anonymous.

    Declaration

    Objective-C

    @property (nonatomic) BOOL useTokenAuth;

    Swift

    var useTokenAuth: Bool { get set }