TikTok for Developers

Migration guidance for OAuth endpoints

If your app is not configured for web and does not use Login Kit for Web, you may ignore this document.

TikTok is making some changes to our developer products to improve security for developers and TikTok end users. As our first improvement, we are improving our OAuth API for obtaining user authorization and managing user access. Our new v2 OAuth API is based on industry standards for OAuth 2.0 as described in RFC 6749.

This document explains how to migrate from v1 OAuth API to v2 OAuth API, including:

  1. Updating your Login Kit configuration to use web redirect URIs for v2 OAuth APIs.
  2. Updating your service integration to work with v2 OAuth API endpoints, requests, and responses.

Timeline

v1 OAuth will stop working on February 29, 2024 for web apps! We recommend you migrate to v2 OAuth APIs as soon as possible using the instructions below.

  • May 12, 2023: All new apps registered on TikTok for Developers must use v2 OAuth APIs.
  • June 12, 2023: Developers will no longer be able to add or modify redirect domains in their Login Kit configurations for web apps.
  • February 29, 2024: End of life for v1 OAuth API, for web apps only. API calls to old endpoints will be rejected.

Required Actions

Register redirect URI

First, follow these steps to register redirect URIs for your web applications:

  1. Find all apps with Login Kit enabled for web:
    1. Navigate to the page to Manage apps.
    2. For each app you own, check if Login Kit is added as a product.
    3. If Login Kit is added, check if the Configure for Web toggle is on.
  1. You will see a banner asking you to provide a redirect URI. You must add at least one URI but you may add up to 10 redirect URIs.

Your redirect URIs must:

  • be less than 512 characters.
  • be absolute and begin with https. For example:
    • Correct: https://dev.example.com/auth/callback/
    • Incorrect: dev.example.com/auth/callback/
  • be static. Parameters will be denied. For example:
    • Correct: https://dev.example.com/auth/callback/
    • Incorrect: https://dev.example.com/auth/callback/?id=1
  • not include a fragment or hash character (#). For example:
    • Correct: https://dev.example.com/auth/callback/
    • Incorrect: https://dev.example.com/auth/callback/#100

You don't need to remove previously configured redirect domains.

Use v2 OAuth APIs

After you register a redirect URI for your app, you can use v2 OAuth APIs to initiate user authorization and manage tokens. The following table summarizes the endpoint mappings between v1 and v2 APIs. Please follow the guidance here for more details.

Functionality

V1 endpoint

V2 endpoint

Initiate authorization grant flow

https://www.tiktok.com/auth/authorize/

https://www.tiktok.com/v2/auth/authorize/

Get an access token

https://open-api.tiktok.com/oauth/access_token/

https://open.tiktokapis.com/v2/oauth/token/

With grant_type=authorization_code

Refresh an access token

https://open-api.tiktok.com/oauth/refresh_token/

https://open.tiktokapis.com/v2/oauth/token/

With grant_type=refresh_token

Revoke an access token

https://open-api.tiktok.com/oauth/revoke/

https://open.tiktokapis.com/v2/oauth/revoke/

Frequently Asked Questions

1. Can I still use v1 OAuth APIs before my app migrates to v2?

Our v1 OAuth APIs are available for use until their end of life for web apps on February 29, 2024. However, you should not use v1 and v2 APIs in a mixed way. For example, you should not use a v1 refresh token API to refresh an access token using the refresh token obtained by v2 token API.

2. Do v2 OAuth APIs support customized query parameters in redirect URI? If not, what should I do if I use such redirect URI in v1 https://www.tiktok.com/auth/authorize/ endpoint?

No, query parameters are not allowed in redirect URI. However, you can fully use the state field to include any customized information. This field will be included in the redirect URI returned by service and the value will not be changed.

3. Are there any changes to error handling for v2 OAuth APIs?

Yes. Error handling for v2 APIs is different from v1 APIs. For more details, see OAuth error handling.

4. Is application/x-www-form-urlencoded the only supported content type for v2 token management APIs?

Yes. You must set Content-Type header with value application/x-www-form-urlencoded before calling v2 token management APIs. Other content type headers are not supported.

5. If my client key is also configured for Android or iOS, should I migrate mobile apps to v2 APIs?

No, mobile apps should continue using v1 OAuth endpoints until further notice.

Need additional support?

Please contact us if you have any more questions or need additional help with this migration.