Create applications that integrate with Typeform's APIs

Typeform uses OAuth 2.0 to secure the endpoints for the Create, Responses, and Webhooks APIs. To use our APIs, you need to pass an access token in the Authorization header of your requests. Our Embed SDK doesn't require an access token.

If you're familiar with using OAuth 2.0 libraries and building apps that use OAuth 2.0 authentication, here's the information you need to get started:

VariableValue
clientIdUnique Typeform client identifier. Find in the Applications section of your Typeform admin panel.
clientSecretUnique secret identifier for Typeform clients. Find in the Applications section of your Typeform admin panel.
redirectUriURL where the application should redirect after users log in and grant access.
urlAuthorizehttps://api.typeform.com/oauth/authorize
urlAccessTokenhttps://api.typeform.com/oauth/token

For more details, read on!

You need to register your application in your Typeform account for it work with the Typeform OAuth 2.0 mechanism. When you register your app, you'll receive the client_id and client_secret for your application, which are used during the OAuth 2.0 process to generate an access token. Here's a diagram of Typeform's OAuth 2.0 flow to illustrate how it works:

Typeform's OAuth 2.0 authentication flow

Access tokens are long strings of random characters that look something like this: 943af478d3ff3d4d760020c11af102b79c440513.


NOTE: Anyone with the access token can read, update, and delete your app users' typeforms and data, so keep access and refresh tokens and client_id and client_secret codes safe! Also, don't commit to source control with access or refresh tokens, or your client_id or client_secret in your code — use a placeholder like CLIENT_ID (or CLIENT_SECRET) instead.


Let's walk through the steps to register your application and start working with Typeform's APIs. Here's the code for the example we're using to illustrate the steps.

1. Create an application in the Typeform admin panel

  1. Log in to your account at Typeform.
  2. In the upper-left corner, click icon drop-down menu next to your organization name.
  3. Under Organization section, click Developer Apps.
  4. Click Register a new app.
  5. In the App Name field, type the name for your new app.
  6. In the App website field, type the complete URL for your app's homepage.
  7. In the Redirect URI(s) field, type the complete callback URL for your app.
  8. Click Register app.

2. Find your app's client_id and client_secret

After you save your app, the app's client_secret will be shown only once. Make sure you copy it and store it somewhere safe.

After that, you'll be able to see the client_id in the Developer Apps panel.

NOTE: If you didn't copy the client_secret, lost it, or suspect that it could be compromised, you can regenerate it. In the Edit app panel, click the Regenerate client secret button to generate a new one.

3. Write your application

Now that you've created your app with Typeform, you can write the application itself. Your application will need to generate an access token (and possibly also a refresh token) to integrate with Typeform's APIs. This requires making authorization and authentication requests through your browser-based application.

The first request, GET https://api.typeform.com/oauth/authorize, confirms your client_id, prompts the user to grant the permissions your app requires, and returns a temporary authorization code. The second request, POST https://api.typeform.com/oauth/token, confirms your temporary authorization code and returns your access token.

Your application's https://api.typeform.com/oauth/authorize link, including parameters, might look like this:

https://api.typeform.com/oauth/authorize?state=xyz789&client_id={your_client_id}&redirect_uri=https://results-example.herokuapp.com/callback&scope={scope1}+{scope2}+{scope3}

This table describes each parameter:

ParameterTypeDescriptionRequired?
statestringValue you can include to help prevent cross-site request forgery (XSRF) attacks. The authorization server preserves the state value from the request and makes it available to the client in the response (when redirecting users back to the client).Optional
client_idstringUnique Typeform client identifier. Find in the Applications section of your Typeform admin panel.Required
redirect_uristringURL where the application should redirect after users log in and grant access. We recommend using https for your redirect_uri because it is more secure. If you use https, your SSL/TLS certificate must be validated — self-signed certificates will not work.Required
scopestringSpace-delimited list that identifies the extent of access that your application requires. OAuth 2.0 scopes are listed on the consent page that the user sees.Required

Clicking the https://api.typeform.com/oauth/authorize link in your app should redirect to the Typeform login screen so users can log in to their Typeform accounts. Then, they'll see a consent screen that lists the scope of access and prompts them to grant or deny access to your app. Here's an example consent screen:

Image of example app consent screen

If the user grants access to your app, Typeform generates a temporary authorization code and redirects the browser to a URL that includes the code. Here's what that redirect URL might look like:

https://results-example.herokuapp.com/callback?code={temporary_authorization_code}&state=xyz789

Now that the application has a temporary authorization code, it can request an access token with POST https://api.typeform.com/oauth/token, sending the temporary authorization code, client_id, client_secret, and redirect_uri in the request body.

Your application's https://api.typeform.com/oauth/token request, including the body, might look like this:

curl --request POST \
  --url https://api.typeform.com/oauth/token \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code={temporary_authorization_code}' \
  --data-urlencode 'client_id={your_client_id}' \
  --data-urlencode 'client_secret={your_client_secret}' \
  --data-urlencode 'redirect_uri=https://results-example.herokuapp.com/callback'

This table describes each part of the request body:

ParameterTypeDescriptionRequired?
grant_typestringAlways set value to authorization_code.Required
codestringTemporary authorization code.Required
client_idstringUnique Typeform client identifier. Find in the Applications section of your Typeform admin panel.Required
client_secretstringUnique secret identifier for Typeform clients. Find in the Applications section of your Typeform admin panel.Required
redirect_uristringURL where the application should redirect. Should contain the same value as the redirect_uri you passed to the https://api.typeform.com/oauth/authorize endpoint. Used only for verification.Required

Typeform then verifies all the data in the request body. If everything is OK, Typeform will send an access token to the application in a JSON response as per RFC 6749.

ParameterTypeDescription
token_typestringAccess token type. Always bearer.
access_tokenstringAccess token.
expires_inintAccess token expiration period. In seconds.
refresh_tokenstringRefresh token. Include only if you specified the offline scope during the authorization code request.

Applications that use the Create and Responses APIs must pass a valid access token in the Authorization header of every request.


NOTE: The default expiration period for the access tokens is 1 week.

After the token expires, your application won't be able to make requests with that token. You will need to get a new token either through the OAuth2 authentication process or by using the token refresh process in Step 4 (below).


4. Refresh your application's tokens

If your application needs to call the Typeform APIs over longer periods of time without user involvement, your application can request a special refresh token during the first authentication call, then use this refresh token to obtain new access tokens without asking for user permission each time.

To receive a refresh token in the first place, your application must pass an extra offline scope during the authorization code request:

https://api.typeform.com/oauth/authorize?state=xyz789&client_id={your_client_id}&redirect_uri=https://results-example.herokuapp.com/callback&scope=offline+{scope1}+{scope2}+{scope3}

If the user agrees to grant your application the required permissions, in the authorization code response to the access token exchange request, your application will receive the access_token and an extra parameter called refresh_token. You can use the value of this refresh_token parameter to obtain a new access token at any time as per RFC 6749.

curl --request POST \
  --url https://api.typeform.com/oauth/token \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token={your_refresh_token}' \
  --data-urlencode 'client_id={your_client_id}' \
  --data-urlencode 'client_secret={your_client_secret}' \
  --data-urlencode 'scope={scope1} {scope2}'

This table describes each part of the request body:

ParameterTypeDescriptionRequired?
grant_typestringAlways set value to refresh_token.Required
refresh_tokenstringRefresh token.Required
client_idstringUnique Typeform client identifier. Find in the Applications section of your Typeform admin panel.Required
client_secretstringUnique secret identifier for Typeform clients. Find in the Applications section of your Typeform admin panel.Required
scopestringSpace-delimited list that narrows the extent of access that your newly obtained token requires. You cannot ask for a wider scope than your initial authorization request scope.Optional

The response for this request is nearly identical to the response for the authorization code to the access token exchange request. The only difference that this response will always include the refresh_token parameter, which will contain the newly generated refresh token.


NOTE: For security purposes, the refresh procedure will invalidate the old refresh token. Therefore, your application won't be able to use the old refresh token anymore. Instead, your application should use the newly generated refresh token returned in the response to this query.


What's next?

Create your own applications that integrate with Typeform's APIs! If you're looking for inspiration, you can find out what other open-source developers are doing on our Community projects page.

You can also take a look at an explanation for a JSON response from our Responses API to see how they're structured. Or head straight to one of our APIs to learn more about how they work and available endpoints — they're listed on the left side of the page.

If you want to directly access Typeform's APIs (for example, using cURL or Postman), learn how to get a personal access token and start making requests.