Skip To Content ArcGIS for Developers Sign In Dashboard

Connecting to a portal

Conceptually, a user always connects to a portal to access GIS content. If users are part of an organization subscription, they may connect to a "sandboxed" area of the portal earmarked for that organization.

AGSPortal is the main class and the entry point into the API for working with portals. It has a delegate that is informed when operations on the portal complete successfully or encounter an error.

Initiate a connection

To connect to a portal or an organization's subscription within a portal, you instantiate an AGSPortal object. This prompts a connection to be established in the background. The connection is agnostic of what is being connected to, a general portal or a specific subscription, and depends upon the URL and the credential used while instantiating the object. There are two cases:

URL points to a general portal

If the URL points to a general portal and if no credential is provided, AGSPortal connects to that portal as an anonymous user. The example below shows how to connect to the portal as an anonymous user.

let url = NSURL(string: "")
self.portal = AGSPortal(URL: url, credential: nil)
When you create the portal object, you need to ensure its memory does not get deallocated before it has a chance to execute. To do this, you need to retain the portal object if you're using manual retain-release, or create a strong reference to it if you're using ARC. See Apple's Memory Management Programming Guide for more information on how to manage object memory.

Credential is provided

If a credential is provided, AGSPortal transparently connects to an organization's subscription within that portal if the credentials belong to a user who is authorized to access the subscription. Therefore, in the example below, if the user john_doe belongs to an organization's subscription within, the portal automatically connects to that subscription.

let url = NSURL(string: "")
let credential = AGSCredential(user: "john_doe", password: "<password>")
//Must provide authType and tokenUrl
credential.authType = .Token
credential.tokenUrl = NSURL(string: "")
self.portal = AGSPortal(URL: url, credential: credential)

If credentials don't belong to a subscription user, AGSPortal connects to the general portal as that user.

URL points to a specific organization's subscription

If the URL points to a specific organizations's subscription within a portal, AGSPortal connects to that subscription. If the subscription allows anonymous access, a credential is not required for the connection. Otherwise, provide the credentials of a user who is authorized to access the subscription.

let url = NSURL(string: "")
//Credential to access the portal
let credential = AGSCredential(user: "john_doe", password: "<password>")
self.portal = AGSPortal(URL: url, credential: credential)

Verify the connection was successful

To verify whether the connection was successful and that information about the portal/subscription loaded properly, set one of your classes as the delegate of AGSPortal.

self.portal.delegate = self

Adopt the <AGSPortalDelegate> protocol in your class swift file and implement the relevant methods.

class MyViewController: UIViewController, AGSPortalDelegate {  

 func portalDidLoad(portal: AGSPortal!) {
  //now it is safe to access the portal's properties
 func portal(portal: AGSPortal!, didFailToLoadWithError error: NSError!) {
  //handle or report the error


You may encounter connection problems if the portal's digital certificate is not signed by a trusted root server. When this happens, you get an error code of type NSURLErrorServerCertificateUntrusted. Work around this problem by adding the host name of the portal to the list of trusted hosts as follows:

//handle or report the error
if error.code == NSURLErrorServerCertificateUntrusted {
 //add host to trusted list
 //retry connecting to portal
 self.portal.resubmitWithURL(url, credential: credential)

When you successfully connect to a specific subscription, information about the portal and organization who owns the subscription returns in the AGSPortalInfo object. However, when you connect just to the general portal, only information about the portal returns. Among other things, the information includes details such as the default base map used in the portal or by the organization, the predefined queries that can be used to find featured groups and items of the portal or organization, a thumbnail image, and so on. This information is encapsulated in an AGSPortalInfo object which is available through the portalInfo property on AGSPortal.

See Also