Using GuideStar API Keys - Authentication

Document created by JackCowardin Administrator on Nov 7, 2016Last modified by JackCowardin Administrator on Jan 3, 2017
Version 13Show Document
  • View in full screen mode

The APIs at data.guidestar.org/  (or quickstartdata.guidestar.org or sandboxdata.guidestar.org) require a login to retrieve data. When you purchase a subscription to a production API or request an API account to use with the QuickStart or Sandbox APIs, your GuideStar Username and Password can be used to access the APIs you are authorized to use. You will also be provided an API Key that is the recommended method for API authentication. The API Key can be used in place of the user name, without a password, to access your APIs. Multiple API keys can be assigned if required. Contact GuideStar Customer Support to request API keys.

 

Users will have a separate key for each API for which they have a subscription.  If you are testing in a browser, use the key in place of the User ID, and leave the password blank.

 

Be aware that a browser will typically cache the most recent key or Username / Password pair used to login.  So if you call one API using a key, and then call a separate API without clearing your browser cache, you will get an authorization error. Either open a new 'private' (or 'incognito') browser window, or close and re-open the browser, or clear the browser cache. The Username / Password combination will not require that authentication information be cleared between API calls, provided the user has a subscription for all the APIs being called.

 

To see your subscriptions and API keys on www.guidestar.org, you can sign in to the site using your Username (email address) and Password, then click on the drop-down at the top right and select My Account, and then select Manage My Subscriptions.

 

My Account link on GuideStar.org

 

For programmatic access to APIs, the authentication method to use is basic authentication. (Basic access authentication - Wikipedia). The Username / Password or API key with a blank password are added as HTTP headers ion the web request. See examples at:  API Code Examples

 

Username and password are added to HTTP Headers or, in the case of the use of the API Key, use the key as the user name and use an empty string as the password. See code sample here ( Search API Code Samples ) for an example of using the API key in code.

 

API Keys are now the recommended authentication method for GuideStar APIs.

 

Historically, username/password pairs have been used to authenticate (login) to the GuideStar APIs. The username and password (credentials) used to authenticate to the APIs are the same as those for the guidestar.org user account that has purchased the API subscription. Previously, if you were a GuideStar API subscriber, your GuideStar website credentials were the only means to login to all of the GuideStar APIs you subscribed to. While this method works well, it was problematic because, if a user changed their guidestar.org password, any software that used that username/password to call the GuideStar APIs also needed to be changed to use the updated credentials.

 

API Keys, on the other hand, are API-specific and are not affected by a password change on guidestar.org. You have an API key for each API that you've purchased. In addition, you may request multiple valid keys for a particular API, and all will work.

 

While you can still access all of your APIs using your GuideStar website credentials, you can also provide only your API key to login--no password is required. This means, however, that your API key for CharityCheck, for example, cannot be used to authenticate a call to the Exchange API, for example, while your GuideStar username and password will access all APIs equally well. All of your API keys may be found in the Account section of GuideStar.org once you have signed in to the website. API Keys represent access to your GuideStar data, and should be protected as carefully as you protect your password.

 

If you prefer using a username / password pair for API access, GuideStar recommends that you register an "API only" username and password (a developer account) so that any password change to the normal www.guidestar.org account will not inadvertently cause authentication problems in your organization’s software when the password, for example, is changed.

1 person found this helpful

Attachments

    Outcomes