Difference between revisions of "Getting Started"

From Enterprise Help
Jump to: navigation, search
Line 1: Line 1:
 
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 ID''', '''Client Secret''', and'''Authorization Token'''; and then, use that information to retrieve an '''Access Token '''and '''Refresh Token.'''
 
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 ID''', '''Client Secret''', and'''Authorization Token'''; and then, use that information to retrieve an '''Access Token '''and '''Refresh Token.'''
  
=='''Role Definitions'''==
+
== '''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 Owner''' or "'''User'''" is the Fishbowl customer who is giving access to their account.
* The '''Resource Server''' is the Fishbowl API Server used to access the User 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''' ==
  
=='''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'''.
 
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'''.
  
[[File:AdminLink.png|center|border|AdminLink.png]]
+
[[File:AdminLink.png|border|center|AdminLink.png]]
  
 
2. Then click '''Add New Administrator '''at the top of the page.
 
2. Then click '''Add New Administrator '''at the top of the page.
  
<br/>[[File:Addadmin.png|center|border|Addadmin.png]]
+
<br/>[[File:Addadmin.png|border|center|Addadmin.png]]
  
  
Line 19: Line 21:
 
3. Fill out the&nbsp;'''Username''',&nbsp;'''Password''', and&nbsp;'''Email Address'''&nbsp;fields with the desired credentials. Then check the box located under&nbsp;'''API User'''&nbsp;and click&nbsp;'''Save'''.
 
3. Fill out the&nbsp;'''Username''',&nbsp;'''Password''', and&nbsp;'''Email Address'''&nbsp;fields with the desired credentials. Then check the box located under&nbsp;'''API User'''&nbsp;and click&nbsp;'''Save'''.
  
[[File:Apiuser.png|center|border|Apiuser.png]]
+
[[File:Apiuser.png|border|center|Apiuser.png]]
  
 
''Note: If you are the&nbsp;'''''''Site Administrator'''''''for multiple Enterprise Sites you will need to use the&nbsp;'''Add Site Dropdown&nbsp;'''to select the site(s)&nbsp;the user will to access need access to and then check the API User box for each.''
 
''Note: If you are the&nbsp;'''''''Site Administrator'''''''for multiple Enterprise Sites you will need to use the&nbsp;'''Add Site Dropdown&nbsp;'''to select the site(s)&nbsp;the user will to access need access to and then check the API User box for each.''
Line 25: Line 27:
  
  
=='''Generating the Client ID & Client Secret'''==
+
== '''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&nbsp;'''Client ID&nbsp;''''''Client Secret'''&nbsp;you will first need to log into Enterprise as a '''Site Administrator'''&nbsp;then navigate to the&nbsp;'''Administrators&nbsp;'''page found under&nbsp;'''Settings'''.
+
*The '''Client ID''' is considered public information, and is used to build login URLs.
 +
*The '''Client Secret'''
  
<br/>[[File:Addadmin.png|center|border|Addadmin.png]]
+
1. To generate the&nbsp;'''Client ID&nbsp;'''&&nbsp;'''Client Secret'''&nbsp;you will first need to log into Enterprise as a '''Site Administrator'''&nbsp;then navigate to the&nbsp;'''Administrators&nbsp;'''page found under&nbsp;'''Settings'''.
 +
 
 +
<br/>[[File:Addadmin.png|border|center|Addadmin.png]]
  
 
2. On the&nbsp;'''Administrators&nbsp;'''page find the user you intend to generate the Client ID & Client Secret for, and click the&nbsp;'''Paddlock Icon'''&nbsp;next to their user name&nbsp;to access&nbsp;'''Security Settings'''.
 
2. On the&nbsp;'''Administrators&nbsp;'''page find the user you intend to generate the Client ID & Client Secret for, and click the&nbsp;'''Paddlock Icon'''&nbsp;next to their user name&nbsp;to access&nbsp;'''Security Settings'''.
  
<br/>[[File:PaddlockScreen.png|center|border|PaddlockScreen.png]]
+
<br/>[[File:PaddlockScreen.png|border|center|PaddlockScreen.png]]
  
 
3. Now click the Register New Application button to generate the Client ID & Client Secret.
 
3. Now click the Register New Application button to generate the Client ID & Client Secret.
  
[[File:RegisterNewApp.png|center|border|RegisterNewApp.png]]
+
[[File:RegisterNewApp.png|border|center|RegisterNewApp.png]]
  
 
4. You now have the '''Client ID '''& '''Client Secret''' needed to retrieve your '''Authorization Token'''.
 
4. You now have the '''Client ID '''& '''Client Secret''' needed to retrieve your '''Authorization Token'''.
  
<br/>[[File:ClientSecret.png|center|border|ClientSecret.png]]
+
<br/>[[File:ClientSecret.png|border|center|ClientSecret.png]]
  
  
  
=='''Retrieving Authorization Token'''==
+
== '''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.'''
 
<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.'''
  
Line 58: Line 62:
 
2. The '''User '''will then be presented with the '''Authorization Prompt:'''
 
2. The '''User '''will then be presented with the '''Authorization Prompt:'''
  
<br/>[[File:Partnercred.png|center|border|Partnercred.png]]
+
<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.
 
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.
Line 64: Line 68:
 
   https://[redirect_uri]?code=Authorization_Token
 
   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.
 
<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.
  
Line 79: Line 84:
  
  
** 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"
  
  
  
  
** 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
  
  
  
** 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 116: Line 124:
 
  grant_type=refresh_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET &refresh_token=REFRESH_TOKEN_HERE
 
  grant_type=refresh_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET &refresh_token=REFRESH_TOKEN_HERE
  
=='''Error Handling'''==
+
== '''Error Handling''' ==
* '''invalid_request - '''&nbsp;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_request - '''&nbsp;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_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.
+
*'''invalid_client''' - Client authentication failed (invalid Client ID and/or Client Secret)
* '''unauthorized_client''' - The authenticated client is not authorized to use this authorization grant type.
+
*'''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.

Revision as of 11:13, 25 June 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


Retrieving Authorization Token


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

2. The User will then be presented with the Authorization Prompt:


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


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, andClient ID in the Request Body to theResource Server.

POST 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:


    • 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 cGV0ZXI6cXdlcnR5MTIh 
grant_type=authorization_code&code=Authorization_Token&redirect_uri=REDIRECT_URI client_id=CLIENT_ID

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.