Authentication

The Fusioo API uses the OAuth 2 protocol for authentication.

What is OAuth?

The OAuth 2 specification is a flexible authorization framework that describes different methods in which a client application can acquire an access token. Once acquired, you (as a developer) can use such token to authenticate a request to an API endpoint. The Access Token represents the user’s authorization for the client application to access their data on their behalf.

This section will outline how to use OAuth with Fusioo. For more information about OAuth feel free to also take a look at the official OAuth spec.

Fusioo supports three different authentication flows, depending on the type of application you are building:

  1. Authorization Code Grant flow - This flow is the most common way of authentication for web applications.
  2. Implicit Grant flow - You should use this flow if you are building a browser only applications that is not utilizing a backend server.
  3. Password Grant flow - You should use this flow if your client application is intended for internal use only. The user has to share his email and password with your application.

Different Authenticating Flows

Authorization Code Grant flow

To get started, you need to register an application.

  1. In your application the user should be redirected to https://connect.fusioo.com/oauth/authorize with the following query string parameters:

    Parameter Description
    response_typerequired - Should be set to code
    redirect_urirequired - The URI where the user will be redirected on success or error. This must match the Redirect URI specified in your application settings.
    client_idrequired - The Client ID uniquely identifies the application making the request.
    state optional - An arbitrary value used by the application to maintain state between the request and callback. The parameter should be used for preventing cross-site request forgery.

    Full URL example: https://connect.fusioo.com/oauth/authorize?response_type=code&redirect_uri=YOUR_URL&client_id=YOUR_APPLICATION_ID&state=RANDOM_STRING

  2. If the user, denies access, the application will not be authorized to access the user's account. The OAuth flow will then redirect the user back to your application, using the redirect_uri parameter. An additional descriptive parameter (error_description) will be added to let you know that the user denied access.

    http://YOUR_URL?error=access_denied&error_description=Access+denied

  3. If the user clicks Allow, the user will be redirected back to your application. A code will be passed along as a query parameter.
    Parameter Description
    codeThe code which needs to be exchanged for a token via the token exchange endpoint.
    stateThe state parameter that was sent with the authorizing request, if any.
  4. Your application can now use the Token Exchange Endpoint for an Access Token (which usually lasts an hour) and a Refresh Token (which is used to fetch a new Access Token when the current one expires)

    Simply make a POST to https://connect.fusioo.com/oauth/token passing the following parameters:

    Parameter Description
    grant_typerequired - Should be set to authorization_code
    coderequired - The code received in the previous response.
    redirect_urirequired - The URI to redirect to on success or error. This must match the Redirect URL specified in the application settings.
    client_idrequired - The Client ID uniquely identifies the application making the request.
    client_secretrequired - The Client Secret belonging to your application, found in the integrations page.
  5. You will receive an Access Token which you can use to make requests to the API.
    Parameter Description
    access_tokenThe token to use in future requests against the API
    expires_inThe number of seconds the access token is valid, usually 3600 (one hour)
    token_typeThe type of token, in this case, bearer
    refresh_tokenThe refresh token is used to get a new access token without needing to redirect or reauthorize the user
  6. Once the Access Token expires, the application can exchange the Refresh Token received for a new Access Token. This action will take place without redirecting the user. You should send a POST request to https://connect.fusioo.com/oauth/token passing the following parameters:
    Parameter Description
    grant_typerequired - Should be set to refresh_token
    refresh_tokenrequired - The Refresh Token received with the previous Access Token request.
    client_idrequired - The Client ID uniquely identifies the application making the request.
    client_secretrequired - The Client Secret belonging to your application, found in the integrations page.
  7. You will receive a new Access Token which can be used to make requests to the API.
    Parameter Description
    access_tokenThe new access token to use in future requests against the API
    expires_inThe number of seconds the access token is valid, usually 3600 (one hour)
    token_typeThe type of token, in this case, bearer
    refresh_tokenThe new refresh token, which is used to get a new access token without the need to redirect or reauthorize the user

Implicit Grant flow

The implicit grant is similar to the Authorization Code Grant flow, with some differences:

  • It is intended to be used for user-agent-based clients (e.g. single page web apps) that cannot protect the client secret because all of the application code and storage is easily accessible.
  • Instead of the authorization server returning an authorization code which is exchanged for an access token, the authorization server returns an access token.
  • For the Implicit Grant flow, the response_type parameter must be set to token

The flow is performed in 2 steps:

  1. Redirect the user to https://connect.fusioo.com/oauth/authorize with the following query string parameters:

    Parameter Description
    response_typerequired - Should be set to token
    redirect_urirequired - The URI to redirect to on success or error. This must match the Redirect URL specified in the application settings.
    client_idrequired - The Client ID uniquely identifies the application making the request.
    state optional - An arbitrary value used by the application to maintain state between the request and callback. The parameter should be used for preventing cross-site request forgery.

    The client secret is not included here. The assumption is that most of the use cases for implicit grants will be mobile or desktop apps, where the secret cannot be protected.

    Full URL example: https://connect.fusioo.com/oauth/authorize?response_type=token&redirect_uri=YOUR_URL&client_id=YOUR_APPLICATION_ID&state=RANDOM_STRING

  2. When the user authorizes the application, you will receive a redirect back from the authorization endpoint with the following parameters embedded in the fragment portion (the part following the #) of the URL:

    Parameter Description
    access_tokenThis token can then be used to access the API, in this case typically using CORS.
    token_typeWill be set to bearer
    expires_in The number of seconds the token is valid, usually 3600 (one hour)
    stateThe state parameter that was sent with the authorizing request.

    Full URL example: https://YOUR_URL#access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600&state=RANDOM_STRING

Password Grant flow

This flow is suitable for applications that can ask end-users for their email and password. The user credentials are used in a single request and are exchanged for an access token.

In this flow there are no redirects to the Fusioo authorization page. The user provides the email and password directly to the application.

To use the password grant type, simply make a POST to https://connect.fusioo.com/oauth/token with the following body parameters to the authorization server:

Parameter Description
grant_typerequired - Should be set to password.
usernamerequired - The user's email
passwordrequired - The user's password
client_idrequired - The Client ID uniquely identifies the application making the request.
client_secretrequired - The Client Secret belonging to your application, found in the integrations page.

In the response, you will receive an Access Token which you can use to make calls to the API.

Parameter Description
access_tokenThis token can then be used to access the API.
token_typeWill be set to bearer
expires_inThe number of seconds the token is valid, usually 3600 (one hour)
What would you improve in this article?