Difference between revisions of "Getting Started"

From Enterprise Help
Jump to: navigation, search
Line 49: Line 49:
  
  
 
== '''Retrieving Authorization Token''' ==
 
 
<br/>The next step is to get an '''Authorization Token''' from the '''Fishbowl Authorization Service''' using the '''API User''' credentials we created in the first step, the '''Client ID''', and a '''Redirect URI.'''
 
 
The '''Fishbowl Authorization Service''' will only redirect users to a registered URI provided by the '''Client'''. Only 1 URI can be registered per client ID. Any HTTP redirect URIs must be protected with TLS security, so the service will only redirect to URIs beginning with "https". This prevents tokens from being intercepted during the authorization process.
 
 
1. The '''Client '''can create an '''Authorization Link''' sending the '''User '''to:
 
 
  [https://services.fishbowl.com/api/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI https://services.fishbowl.com/api/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI]
 
 
2. The '''User '''will then be presented with the '''Authorization Prompt:'''
 
 
<br/>[[File:Partnercred.png|border|center|Partnercred.png]]
 
 
3. Enter the '''API User '''credentials into the appropriate fields and click '''Authorize. '''Upon validating the username & password the '''Fishbowl Authorization Service '''will redirect the '''User '''to the '''Redirect URI '''used in the '''Authorization Link. '''The '''Client's Authorization Token '''will be appended to the end as a query string.
 
 
  https://[redirect_uri]?code=Authorization_Token
 
  
 
== '''Generating Access Token & Refresh Token''' ==
 
== '''Generating Access Token & Refresh Token''' ==
 
<br/>To obtain an '''Access Token '''& '''Refresh Token, '''the '''Client '''will need to exchange the '''Authorization Code '''for these tokens. The client can use either of the methods below.
 
 
1. The first provide the '''Authorization Token''','''Client Secret''', and'''Client ID '''in the Request Body to the'''Resource Server'''.
 
 
POST [https://services.fishbowl.com/api/oauth2/token https://services.fishbowl.com/api/oauth2/token] HTTP/1.1 Content-Type: application/x-www-form-urlencoded
 
grant_type=authorization_code&code=Authorization_Token&redirect_uri=REDIRECT_URI client_id=CLIENT_ID
 
&client_secret=CLIENT_SECRET
 
 
2. The second option places the '''Client Secret '''in the Authorization Header rather than the Request Body.
 
  
 
The Authorization header is constructed as follows:
 
The Authorization header is constructed as follows:
Line 84: Line 56:
  
  
**Client ID and Client Secret are combined into a string "client_id:client_secret"
+
*
 +
*Client ID and Client Secret are combined into a string "client_id:client_secret"
  
  
Line 90: Line 63:
  
  
**The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line
+
*
 +
*The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line
  
  
Line 96: Line 70:
  
  
**The authorization method and a space i.e. "Basic " is then put before the encoded string.
+
*
 +
*The authorization method and a space i.e. "Basic " is then put before the encoded string.
  
  
Line 103: Line 78:
  
 
  POST [https://services.fishbowl.com/api/oauth2/token https://services.fishbowl.com/api/oauth2/token] HTTP/1.1 Content-Type: application/x-www-form-urlencoded  
 
  POST [https://services.fishbowl.com/api/oauth2/token https://services.fishbowl.com/api/oauth2/token] HTTP/1.1 Content-Type: application/x-www-form-urlencoded  
  Authorization: Basic cGV0ZXI6cXdlcnR5MTIh
+
  Authorization: Basic [Encoded ClientID:ClientSecret]
  grant_type=authorization_code&code=Authorization_Token&redirect_uri=REDIRECT_URI client_id=CLIENT_ID
+
  grant_type=password&username=[API_User_UserName]&password=[API_User_Password]
  
 
The '''Resource Server''' replies with an access token
 
The '''Resource Server''' replies with an access token

Revision as of 12:11, 30 November 2015

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.