Getting Started

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


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


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


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.


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.


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


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


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:

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


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.


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

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 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", 

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 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.