Authentication

Most of the features in the SDK require the SDK to be authenticated with any type of authentication token. The SDK provides several mechanism to perform authentication. The SDK will cache the authentication information until they expire or new information will be provided by a re-authentication call.

warning

Only re-authenticate the SDK, if you have not yet authenticated the SDK or if the current authentication information are not valid anymore.

You don't need to re-authenticate the SDK after every initialization. If you want to check, if an authentication is required you can use the the modules get_current_authentication_method() method to verify, if the SDK is currently successfully authenticated with any known method.
If the return value is None , you have not yet authenticated the SDK or the existing authentication information are not valid anymore.

Too many re-authentications might result in API endpoints to rate limit the request.

Swift

let credentials = AuthCredentials(
    accessToken: "OPENID ACCESS TOKEN", 
    refreshToken: "OPENID REFRESH TOKEN", 
    idToken: "OPENID ID TOKEN"
)
try manager.authentication().openidAuthenticateWithAuthCredentials(
    authCredentials: credentials
)

Kotlin

val credentials = AuthCredentials(
    accessToken = "OPENID ACCESS TOKEN", 
    refreshToken = "OPENID REFRESH TOKEN", 
    idToken = "OPENID ID TOKEN"
)

manager.authentication().openidAuthenticateWithAuthCredentials(
    authCredentials = credentials
)

This method should only be used, if the regular OpenID Web Flow is not available. It only supports authentication with a username and password, while the regular OpenID Authentication might support a variety of authentication methods. This internally uses the Resource-Owner-Password-Credentials Flow specified in the OpenID standard.

Swift

try manager.authentication().openidAuthenticateWithUsernamePassword(
    username: "jon.doe",
    password: "my_secret"
)

Kotlin

manager.authentication().openidAuthenticateWithUsernamePassword(
    username = "jon.doe",
    password = "my_secret"
)

Swift

try manager.authentication().openidAuthenticateWithAuthorizationCode(
    authorizationCode: "XYZ123",
)

Kotlin

manager.authentication().openidAuthenticateWithAuthorizationCode(
    authorizationCode = "XYZ123",
)

Supported Authentication Methods

OpenID Connect

See OpenID Connect Authentication.

Authentication with Opaque Token

In this mode, the SDK will not perform any authentication token validation and will just pass it to the endpoints which will then know how to validate it.

As the SDK internally manages authentication tokens per each user in a separate storage session, the app would need to provide a userId under which the SDK should internally store this token. This can also be any random string.

Swift

try manager.authentication().authenticateWithOpaqueToken(
    userId: "user_1234", 
    token: "ANYTOKEN"
)

Kotlin

try manager.authentication().authenticateWithOpaqueToken(
    userId = "user_1234", 
    token = "ANYTOKEN"
)

Authentication with Legacy XV Authentication

This mode is used by legacy ExpressVPN apps and uses a JWT Access Token.

warning

It's the responsibility to call this method whenever the current access token expired and a fresh one needs to provided.

Swift

let credentials = AuthCredentials(
    accessToken: "<ACCESS TOKEN>", 
    refreshToken: "",  // not needed
    idToken: "",  // not needed
)

try manager.authentication().authenticateWithXvLegacyAuthCredentials(
    authCredentials: credentials
)

Kotlin

val credentials = AuthCredentials(
    accessToken = "<ACCESS TOKEN>", 
    refreshToken = "",  // not needed
    idToken = "",  // not needed
)

manager.authentication().authenticateWithXvLegacyAuthCredentials(
    authCredentials = credentials
)

The SDK allows also to authenticate using the legacy XV user name and password:

Swift

try manager.authentication().authenticateWithXvLegacyUsernamePassword(
    username: "[email protected]",
    password: "my-password"
)

Kotlin

try manager.authentication().authenticateWithXvLegacyUsernamePassword(
    username = "[email protected]",
    password = "my-password"
)

Apple InApp Receipt Authentication

In this mode, you will provide an Apple InApp Receipt to authenticate the SDK using the Authentication with Opaque Token method.

SDK Methods

Getting the currently logged in User

Swift

let userProfile = try manager.authentication().getCurrentUserProfile()

Kotlin

val userProfile = manager.authentication().getCurrentUserProfile()

UserProfile

Name	Type	Description
user_id	Option<String>	Contains the user id of the currently logged in user, None, if no user is logged in
email	Option<String>	Contains the email of the currently logged in user, None, if no user is logged in. This field is only populated when using OpenID authentication.
authentication_method	AuthenticationMethod	Current Authentication Method being used, can be one of None OpenID LegacyXV Opaque

Getting the last known logged in User

This method will return the last successfully authenticated User Profile.

Swift

let lastKnownProfile = try manager.authentication().getLastKnownUserProfile()

Kotlin

val lastKnownProfile = manager.authentication().getLastKnownUserProfile()

Logging out a User

This method will reset the SDK cache, including all cached tokens. This method will not logout from any OpenID Session! You need to implement OpenID Logout on the client side.

Swift

// Logout the SDK by deleting all cache files
manager.authentication().logout()

Kotlin

// Logout the SDK by deleting all cache files
manager.authentication().logout()