Guides

Reference

Guides

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:

URL where the application should redirect after users log in and grant access.

urlAuthorize

https://api.typeform.com/oauth/authorize

urlAccessToken

https://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:

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 ACCESS_TOKEN (REFRESH_TOKEN) 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.

2. Find your app's client_id and client_secret

After you save your app, the app's client_id and client_secret will be listed in the Applications section of you Typeform admin panel. Here's how to find them:

In the upper-right corner, in the drop-down menu next to your profile photo, click My Account.

In the left menu, click Applications.

Click the name of the application.

Scroll to the bottom of the page to see the app's client_id and client_secret.

NOTE: For your account's security, after you leave the page (e.g., by closing the tab or switching to another account section), we will hide the client_secret, and we cannot recover it. Please make sure to copy the client_secret before you leave the page. If you didn't copy the client_secret, lost it, or suspect that it could be compromised, 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.

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

URL 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

scope

string

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

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:

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.

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

Parameter

Type

Description

token_type

string

Access token type. Always bearer.

access_token

string

Access token.

expires_in

string

Access token expiration period. In seconds.

refresh_token

string

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

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.

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.