Getting Started

From Enterprise Help
Revision as of 11:11, 30 November 2015 by Sghosh (Talk | contribs)

Jump to: navigation, search

A Client can access a User's Account with the Resource Server using a Client ID, Client Secret, Access Token, and Refresh Token. The following steps will show you how to create an API User, generate the Client IDClient Secret, andAuthorization Token; and then, use that information to retrieve an Access Token and Refresh Token.

Role Definitions

  • The Resource Owner or "User" is the Fishbowl customer who is giving access to their account.
  • The Client is the application that is attempting to get access to the User Account.
  • The Resource Server is the Fishbowl API Server used to access the User Account.

Creating an API User

1. To create an API User you will first need to log into Enterprise as a Site Administrator; then navigate to the Administrators page found under Settings.

AdminLink.png

2. Then click Add New Administrator at the top of the page.


Addadmin.png


3. Fill out the UsernamePassword, and Email Address fields with the desired credentials. Then check the box located under API User and click Save.

Apiuser.png

Note: If you are the ''Site Administrator''for multiple Enterprise Sites you will need to use the Add Site Dropdown to select the site(s) the user will to access need access to and then check the API User box for each.


Generating the Client ID & Client Secret

  • The Client ID is considered public information, and is used to build login URLs.
  • The Client Secret

1. To generate the Client ID Client Secret you will first need to log into Enterprise as a Site Administrator then navigate to the Administrators page found under Settings.


Addadmin.png

2. On the Administrators page find the user you intend to generate the Client ID & Client Secret for, and click the Paddlock Icon next to their user name to access Security Settings.


PaddlockScreen.png

3. Now click the Register New Application button to generate the Client ID & Client Secret.

RegisterNewApp.png

4. You now have the Client ID & Client Secret needed to retrieve your Authorization Token.


ClientSecret.png


Generating Access Token & Refresh Token

The Authorization header is constructed as follows:


  • Client ID and Client Secret are combined into a string "client_id:client_secret"



  • The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line



  • The authorization method and a space i.e. "Basic " is then put before the encoded string.



POST https://services.fishbowl.com/api/oauth2/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded 
Authorization: Basic [Encoded ClientID:ClientSecret]
grant_type=password&username=[API_User_UserName]&password=[API_User_Password]

The Resource Server replies with an access token

{
"access_token":"u7kBYz1UhHkoRSc7V4gruBs-4sEpIkFV-F4LGiFMwfGwJNnT_JzNftg6_Zm0yWi  o8P m60iPlmCCHUSwCX5Uru-OJq2
jzhbT-E6nAc1OwzghTCmeoo0K69ubDBMFX5hyKlcAjA9H3Vs-ZN jNYKarpSO5rA5ubG5-Va5Aigm9mp-Pre-EaGAY_HBdxZi-LBMSQ_mSjyI
DPBpLFYPBNzK3cu0xGobGs FLxPtDG3urs_4abXZtvxN8wm9rpsgr6nk", 
"token_type":"bearer", 
"expires_in":1799, 
"refresh_token":"717ccad6e5f541ad9bdbf9be950d1c9c" 
}


Access tokens are valid for 30 minutes (expires_in value is expressed in seconds).

When Access Tokens have expired, your server will need to request a new one using the provided refresh token.

POST https://services.fishbowl.com/api/oauth2/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded 
grant_type=refresh_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET &refresh_token=REFRESH_TOKEN_HERE

Error Handling

  • invalid_request -  The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
  • invalid_client - Client authentication failed (invalid Client ID and/or Client Secret)
  • invalid_grant - The provided authorization code is invalid, expired, revoked or does not match the re-direction URI used in the authorization request or was issued to another client.
  • unauthorized_client - The authenticated client is not authorized to use this authorization grant type.