iOS SDK
Integrate your iOS application with Authgear iOS SDK
This guide provides instructions on integrating Authgear with an iOS app. Supported platforms include:
iOS 11.0 or higher
Follow this guide to add Authgear to your iOS app in 🕐 10 minutes.
Setup Application in Authgear
Sign up for an Authgear Portal account at https://portal.authgear.com/. Or you can use your self-deployed Authgear.
From the Project listing, create a new Project or select an existing Project. After that, we will need to create an Authgear client application in the project.
Step 1: Create an application in the Portal
Go to Applications on the left menu bar.

Click ⊕Add Application in the top toolbar.
Input the name of your application and select Native App as the application type. Click "Save".

You will see a list of guides that can help you for setting up, then click "Next".
Step 2: Configure the application
Here you'll need to define a custom URI scheme that Authgear will use to redirect users back to your app after authentication. For our example app, this URL Scheme will be com.example.authgeardemo://host/path
. For further instructions on setting up a custom URI scheme in iOS, see the official documentation here.
Head back to Authgear Portal, and add com.example.authgeardemo://host/path
as Redirect URI.
Click "Save" button and note the Client ID. and Endpoint for your new client application as you'll use them later in your iOS application. You can also obtain the Client ID again from the Applications list later.

Add Authgear to your iOS Application
In this step, we'll add user authentication to a simple iOS app using the Authgear iOS SDK and the client application we created in the previous steps.
Pre-requisites
To follow the steps in this guide seamlessly, you should have the following:
Xcode (Latest Version)
Some knowledge of SwiftUI
Step 1: Create new iOS project
For the purpose of this guide, we'll create a new project in Xcode. Skip this step if you're adding Authgear to your existing app.
To create a new project, open Xcode and navigate to File > New > Project. Create your new project with the following details:
Project Name:
my_demo_app
choose
SwiftUI
as Interface Leave other fields unchanged and proceed to create the project.

Step 2: Install Authgear SDK
The Authgear iOS SDK makes it easy to interact with Authgear services from your iOS project.
To add Authgear SDK to your project, in Xcode navigate to File > Add Package Dependencies and enter https://github.com/authgear/authgear-sdk-ios.git
in the Package URL text field.
Click Add Package to proceed.

On the next screen, select your application under Add to Target then click on Add Package.

Alternatively, if your project uses cocoapods, install the SDK using:
pod 'Authgear', :git => 'https://github.com/authgear/authgear-sdk-ios.git'
Step 3: Initialize Authgear SDK
In this step, we'll initialize an instance of the Authgear SDK when the user interface of our app loads.
For our demo app, add the following code to ContentView.swift
First import Authgear iOS SDK:
import Authgear
In
struct ContentView: View {}
, initialize an instance ofAuthgear()
and call the.configure()
method in an.onAppear()
modifier attached toVStack
like this:
private var authgear: Authgear = Authgear(clientId: "<ClIENT_ID>", endpoint: "<AUTHGEAR_ENDPOINT>")
var body: some View {
VStack {
Image(systemName: "globe")
.imageScale(.large)
.foregroundStyle(.tint)
Text("My Demo App")
}
.padding()
.onAppear() {
authgear.configure() { result in
switch result {
case .success():
// configured successfully
print("// configured successfully")
case let .failure(error):
// failed to configured
print("config failed", error)
}
}
}
}
Replace "<CLIENT_ID>" and "<AUTHGEAR_ENDPOINT>" with the client ID and endpoint from the configuration page of the client project you created earlier.
Step 4: Add Login Button
Now let's add the Login button and other UI elements for the demo app.
Add the following views to VStack
:
VStack {
if isLoading {
ProgressView()
}
if loginState == SessionState.authenticated {
Text("Welcome user \(userId ?? "user")")
Button(action: openUserSettings) {
Text("User Settings")
}
Button(action: logout) {
Text("Logout")
}
} else {
Image(systemName: "globe")
.imageScale(.large)
.foregroundStyle(.tint)
Text("My Demo App")
Button(action: startAuthentication) {
Text("Login")
}
}
}
In addition to the Login button, we've included a ProgressView and a block with views we want only logged-in users to see. Create the isLoading
, userId
and loginState
variables that the if-statement and Text view depend on at the top of the class just after private var authgear: Authgear = Authgear(...)
:
@State private var loginState: SessionState = .unknown
@State private var isLoading: Bool = false
@State private var userId: String? = ""
Step 5: Start Authentication Flow
Implement a startAuthentication()
method in your ContentView
class that will call the authenticate()
method of the Authgear SDK:
func startAuthentication() {
isLoading = true
authgear.authenticate(redirectURI: "com.example.authgeardemo://host/path", handler: { result in
switch result {
case let .success(userInfo):
// login successfully
loginState = authgear.sessionState
userId = userInfo.sub
isLoading = false
case let .failure(error):
if let authgearError = error as? AuthgearError, case .cancel = authgearError {
// user cancel
isLoading = false
} else {
// Something went wrong
isLoading = false
}
}
})
}
In order to get your app to build at this point, add empty declarations for logout and openUserSettings methods:
func logout() {
}
func openUserSettings() {
}
The full code for ContentView.swift
at this point should look like this:
// ContentView.swift
import SwiftUI
import Authgear
struct ContentView: View {
private var authgear: Authgear = Authgear(clientId: "<ClIENT_ID>", endpoint: "<AUTHGEAR_ENDPOINT>")
@State private var loginState: SessionState = .unknown
@State private var isLoading: Bool = false
@State private var userId: String? = ""
var body: some View {
VStack {
if isLoading {
ProgressView()
}
if loginState == SessionState.authenticated {
Text("Welcome user \(userId ?? "user")")
Button(action: openUserSettings) {
Text("User Settings")
}
Button(action: logout) {
Text("Logout")
}
} else {
Image(systemName: "globe")
.imageScale(.large)
.foregroundStyle(.tint)
Text("My Demo App")
Button(action: startAuthentication) {
Text("Login")
}
}
}
.padding()
.onAppear() {
authgear.configure() { result in
switch result {
case .success():
// configured successfully
print("// configured successfully")
case let .failure(error):
// failed to configured
print("config failed", error)
}
}
}
}
func startAuthentication() {
isLoading = true
authgear.authenticate(redirectURI: "com.example.authgeardemo://host/path", handler: { result in
switch result {
case let .success(userInfo):
// login successfully
userId = userInfo.sub
loginState = authgear.sessionState
isLoading = false
case let .failure(error):
if let authgearError = error as? AuthgearError, case .cancel = authgearError {
// user cancel
isLoading = false
} else {
// Something went wrong
isLoading = false
}
}
})
}
func logout() {
}
func openUserSettings() {
}
}
#Preview {
ContentView()
}
Checkpoint
Run your app now. When you click on the Login button, you should be redirected to the user authentication page.

Step 6: Register URI Schema for Redirect URI
Open your project's Info.plist
or project settings UI in Xcode and add the following:
Navigate to Targets > {Your project} > Info and expand the URL Types section.
Add a new URL scheme with the following details:
Identifier: CFBundleURLTypes
URL Schemes: com.example.authgeardemo://host/path
Role: Editor

Now run your app again and try logging in. Because we've set up a redirect URL, Authgear should redirect back to our app correctly.
Step 7: Implement Logout method
Implement the logout method that will be executed when the Logout button is clicked by updating the empty logout function we added in the previous step:
func logout() {
isLoading = true
authgear.logout { result in
switch result {
case .success():
// logout successfully
isLoading = false
loginState = authgear.sessionState
case let .failure(error):
print("failed to logout", error)
isLoading = false// failed to login
}
}
}
Now clicking on the Logout button will call Authgear SDK's logout method and end the current user session.
Step 8: Show the user information
In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the fetchUserInfo
function to obtain the user info, see example.
The Authgear SDK can return the current user's details via the UserInfo object. The authenticate method returns this userInfo object as demonstrated earlier in our app's startAuthentication()
method. You can also call the SDK's .fetchUserInfo()
method to get the UserInfo object.
Add a new getCurrentUser()
method to your ContentView
class:
func getCurrentUser() {
isLoading = true
authgear.fetchUserInfo { userInfoResult in
// sessionState is now up to date
// it will change to .noSession if the session is invalid
loginState = authgear.sessionState
switch userInfoResult {
case let .success(userInfo):
// read the userInfo if needed
userId = userInfo.sub
isLoading = false
case let .failure(error):
// failed to fetch user info
// the refresh token maybe expired or revoked
print("the refresh token maybe expired or revoked", error)
isLoading = false
}
}
}
Now call the new getCurrentUser()
method in the .onAppear()
modifier of the VStack
like this:
.onAppear() {
authgear.configure() { result in
switch result {
case .success():
// configured successfully
// refresh access token if user has an existing session
if authgear.sessionState == SessionState.authenticated {
getCurrentUser()
}
case let .failure(error):
// failed to configured
print("config failed", error)
}
}
}
This will make your app refresh the access token and greet users who are already logged in with their sub
(a unique user ID) when the launch the app. You can read other user attributes like email address, phone number, full name, etc. from userInfo.
Step 9: Open User Settings page
Authgear offers a pre-built User Settings page that user's can use to view, and modify their profile attributes and security settings.
Implement the empty openUserSettings()
method we added in the previous step to call the .open()
method of the Authgear SDK:
func openUserSettings() {
authgear.open(page: SettingsPage.settings)
}
Get the Logged In State
When you start launching the application. You may want to know if the user has logged in. (e.g. Show users a Login button if they haven't logged in).
The sessionState
reflects the user logged-in state in the SDK local state. That means even if the sessionState
is .authenticated
, the session may be invalid if it is revoked remotely. Hence, after initializing the Authgear SDK, call fetchUserInfo
to update the sessionState
as soon as it is proper to do so. We demonstrated how to use sessionState
, and fetchUserInfo
, to get a user's true logged-in state and retrieve their UserInfo in Step 8.
The value of sessionState
can be .unknown
, .noSession
or .authenticated
. Initially, the sessionState
is .unknown
. After a call to authgear.configure
, the session state would become .authenticated
if a previous session was found, or .noSession
if such session was not found.
Using the Access Token in HTTP Requests
Call refreshAccessTokenIfNeeded
every time before using the access token, the function will check and make the network call only if the access token has expired. Include the access token in the Authorization header of your application request.
authgear.refreshAccessTokenIfNeeded() { result in
switch result {
case .success():
// access token is ready to use
// accessToken can be empty
// it will be empty if user is not logged in or session is invalid
// include Authorization header in your application request
if let accessToken = authgear.accessToken {
// example only, you can use your own networking library
var urlRequest = URLRequest(url: "YOUR_SERVER_URL")
urlRequest.setValue(
"Bearer \(accessToken)", forHTTPHeaderField: "authorization")
// ... continue making your request
} else {
// The user is not logged in, or the token is expired.
}
case let .failure(error):
// Something went wrong
}
}
Next steps
To protect your application server from unauthorized access. You will need to integrate your backend with Authgear.
Backend/API IntegrationiOS SDK Reference
For detailed documentation on the iOS SDK, visit iOS SDK Reference.
Last updated
Was this helpful?