OAuth2 allows external apps access to FluidSurveys users data without requiring their password. This allows users to limit the access of externals apps and revoke access to external apps though FluidSurveys.


If you would like to request authorization from FluidSurveys users you must first reigster your application on the developer page and provide your:

  • application name
  • homepage url
  • callback url
  • description

You will recieve a client_id and secret. Keep this safe! We recommend storing these as environment variables.

Authentication Flow

Follow the following steps to complete the authorization flow:

1. Redirect to FluidSurveys

Create a link on your site to ask the user to authorize your application.

GET https://fluidsurveys.com/accounts/developer/authorize/
Query Parameters:
  • response_type – this should be code
  • client_id – your client_id
  • redirect_uri – your redirect_uri

2. FluidSurveys redirects back your application

Once the user has authorized your application, they will be redirected back to your redirect_uri. Included in the request will be a code query parameter. You may then trade this code for an access token in the next step.

3. Obtain Bearer Token

POST https://fluidsurveys.com/accounts/oauth/token/
Form Parameters:
  • code – the code you recieved from the redirect
  • client_id – your client_id
  • client_secret – your client_secret
  • redirect_uri – your redirect_uri
  • grant_type – should be authorization_code
curl -u bob@example.com:PASSWORD -d "code=12345&client_id=demo&client_secret=SECRET
&redirect_uri=http://www.example.com/fluid/&grant_type=authorization_code" \
  "access_token": "DCFUHW92F3HF2E2F2F20H"

4. Making Requests

You can now make API requests on behalf of the user. Set the Authorization header to include the access token.

curl --header "Authorization: Bearer DCFUHW92F3HF2E2F2F20H" \
{"templates": "http://fluidsurveys.dev:8000/api/v3/templates/",
 "surveys": "http://fluidsurveys.dev:8000/api/v3/surveys/",
 "collectors": "http://fluidsurveys.dev:8000/api/v3/collectors/",
 "contacts": "http://fluidsurveys.dev:8000/api/v3/contacts/",
 "embeds": "http://fluidsurveys.dev:8000/api/v3/embeds/",
 "contact-lists": "http://fluidsurveys.dev:8000/api/v3/contact-lists/",
 "webhooks": "http://fluidsurveys.dev:8000/api/v3/webhooks/"