TikTok API for Business access tokens: 24 hours, refresh and revoke
A TikTok API for Business access token lasts 24 hours and travels in the Access-Token header. An app gets it by exchanging the owner's authorization code at /tt_user/oauth2/token/, along with a refresh token that lasts a year and renews access at /tt_user/oauth2/refresh_token/. Revoke it at /tt_user/oauth2/revoke/, and list its granted scopes at /tt_user/token_info/get/.
easyCoexistence exchanges the code when a TikTok account signs in, renews the 24-hour token before it runs out and checks the account about every 6 hours, so Claude, ChatGPT or your own code calls TikTok with a current token, which get_social_credentials hands to your scripts.
Lifetime of a TikTok account access token; each token response states the seconds left in expires_in.
Validity of the refresh token issued with it; refresh_token_expires_in gives its remaining seconds.
How long the authorization code in the redirect stays valid; it can be exchanged only once.
The account's application-specific ID, returned with each token and sent as business_id on Accounts API calls.
The token_type TikTok returns: whoever holds the token can use it to reach the account's resources.
The account ID /tt_user/token_info/get/ returns beside the token's scope, usable as business_id on Accounts API calls.
How does the authorization code reach your app?
Through the TikTok account holder authorization URL, which TikTok generates for a developer app under My Apps, App Detail, Basic Information once the app holds the TikTok Accounts permission. The account owner opens it, reviews the permissions and approves them. TikTok then sends the browser to the app's redirect URL with an auth_code appended, plus any state value the authorization URL carried, and that code is valid for 10 minutes and a single exchange.
- Redirect URL: absolute, starting with https://, ending in /, with no query string, anchor or port, and 10 to 512 characters long.
- Up to 10 redirect URLs per app, one active at a time; activating one generates its own authorization URL.
- state: an optional value TikTok echoes back on the redirect, which it suggests as a guard against CSRF.
disable_auto_auth=1: shows the review page to owners who approved the same permissions before, whom TikTok otherwise redirects at once.
How do you exchange the code for tokens?
With a POST to /tt_user/oauth2/token/ from your server, as JSON. client_id and client_secret are the App ID and Secret shown under My Apps, App Detail, Basic Information; grant_type is authorization_code; auth_code is the code from the redirect; and redirect_uri has to equal the TikTok account holder redirect URL set in the app.
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/tt_user/oauth2/token/' \
-H 'Content-Type: application/json' \
-d '{
"client_id": "<APP_ID>",
"client_secret": "<APP_SECRET>",
"grant_type": "authorization_code",
"auth_code": "<AUTH_CODE>",
"redirect_uri": "https://app.example.com/tiktok/callback/"
}'What does the token response contain?
A JSON object with code, message, request_id and data. A code of 0 means the exchange worked, and data carries both tokens and the account's ID:
access_token: the short-term token for API calls, valid for one day.token_type: Bearer, which TikTok describes as usable by anyone in possession of the token.- scope: the permissions granted to the token, as one comma-separated string.
expires_in: the seconds remaining before the access token expires, 86400 in TikTok's example.refresh_token: the token that renews access, valid for one year; TikTok's note is to retain it.refresh_token_expires_in: the seconds remaining before the refresh token expires.open_id: the application-specific ID of the TikTok account.
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": {
"access_token": "<ACCESS_TOKEN>",
"token_type": "Bearer",
"scope": "user.info.basic,user.info.stats,user.insights,video.list,video.insights,video.publish,comment.list,comment.list.manage",
"expires_in": 86400,
"refresh_token": "<REFRESH_TOKEN>",
"refresh_token_expires_in": 31536000,
"open_id": "<OPEN_ID>"
}
}How is the token sent on API calls?
In a request header named Access-Token, on Accounts API endpoints from /business/get/ to /business/video/publish/, while the account itself is named in business_id, set to the open_id from the same response. The OAuth endpoints work the other way round: /tt_user/oauth2/token/, /tt_user/oauth2/refresh_token/ and /tt_user/oauth2/revoke/ take the app's client_id and client_secret in a JSON body and no Access-Token header.
How do you renew the access token?
With a POST to /tt_user/oauth2/refresh_token/ carrying client_id, client_secret, grant_type set to refresh_token, and the stored refresh_token. The answer has the same fields as the first exchange: a new access_token with its expires_in, a refresh_token to keep for the next renewal and the seconds that one has left. Schedule the renewal ahead of the 24 hours rather than waiting for error 40102.
import os, time, requests
API = "https://business-api.tiktok.com/open_api/v1.3"
def renew(refresh_token: str) -> dict:
r = requests.post(f"{API}/tt_user/oauth2/refresh_token/", json={
"client_id": os.environ["TIKTOK_APP_ID"],
"client_secret": os.environ["TIKTOK_APP_SECRET"],
"grant_type": "refresh_token",
"refresh_token": refresh_token,
}, timeout=30).json()
if r["code"] != 0: # 40103: the refresh token expired, so the owner authorizes again
raise RuntimeError(f"{r['code']}: {r['message']}")
d, now = r["data"], time.time()
return {
"access_token": d["access_token"],
"access_expires_at": now + d["expires_in"],
"refresh_token": d["refresh_token"], # keep it for the next renewal
"refresh_expires_at": now + d["refresh_token_expires_in"],
}How do you revoke access?
From the app, with a POST to /tt_user/oauth2/revoke/ holding client_id, client_secret and the access_token to revoke; success returns code 0 with an empty data object. From the account, the owner opens the TikTok app, goes to Settings and privacy, Security, Manage app permissions, picks the app and chooses Remove access. Once the authorization is revoked, TikTok stops sending the app comment.update events for that account.
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/tt_user/oauth2/revoke/' \
-H 'Content-Type: application/json' \
-d '{"client_id": "<APP_ID>", "client_secret": "<APP_SECRET>", "access_token": "<ACCESS_TOKEN>"}'
# {"code": 0, "message": "OK", "request_id": "<REQUEST_ID>", "data": {}}How do you inspect a token?
With a POST to /tt_user/token_info/get/, which needs no permission of its own: send app_id and the access_token, and data returns app_id, scope and creator_id. scope lists what the owner granted, and creator_id is the account's application-specific ID, the value Accounts API calls take as business_id. TikTok's references send developers here whenever a field needs a scope the token may lack.
Which errors come from tokens?
TikTok puts them in the code field of the response, usually under HTTP status 200, so check code before trusting a call. The return codes tied to tokens and to their exchange:
- 40102: the access token has expired; renew it and call again.
- 40103: the refresh token has expired; only a new authorization by the owner replaces it.
- 40104: the request carried no access token.
- 40105: the access token is invalid or incorrect.
- 40107: the refresh token is invalid or incorrect, for example one sent to renew a Marketing API token, which never expires.
- 40110: the authorization code was cancelled, already used or has expired.
- 40131: an authentication error at the two token endpoints, from a wrong app ID or secret, an expired code, or an invalid or expired refresh token.
What does easyCoexistence renew for you?
Everything after the sign-in. easyCoexistence exchanges the code as soon as TikTok redirects back, stores both tokens encrypted, and renews the access token itself: before a call when less than 15 minutes remain, and during the check it runs on each account about every 6 hours when less than 8 hours remain. Each renewal stores the new refresh token and its expiry, and calls that arrive together share one renewal.
- Rejected token: when TikTok answers 40102, 40104 or 40105, the connection is marked for reconnecting and the owner gets an email; Partner API users also receive channel.disconnected.
- Your own code:
get_social_credentials, or GET /channels/{id}?credentials=1 on the Partner API, returns the current token withtoken_expires_at, so fetch it per job. - Removal: removing the connection in the dashboard, or with DELETE /channels/{id}, revokes the token at TikTok through /
tt_user/oauth2/revoke/.
Common mistakes
- Exchanging the authorization code in the browser. The exchange sends the app's client_secret, so make it from your server, within 10 minutes of the redirect.
- Reading expires_in as a date. It holds the seconds remaining, so add it to the time of the response to know when the token expires.
- Revoking with the refresh token. /tt_user/oauth2/revoke/ takes the access_token, together with the app's client_id and client_secret.
- Treating a missing consent screen as a failure. TikTok skips the review page for permissions the owner approved before; append disable_auto_auth=1 to show it again.
US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
How long does a TikTok API for Business access token last?
24 hours. Each token response gives the seconds left in expires_in, and the refresh token, valid for a year, renews it.
Does the TikTok refresh endpoint need redirect_uri?
Its parameter table lists client_id, client_secret, grant_type and refresh_token, with no redirect_uri, though TikTok's authentication guide says its token endpoints require redirect_uri.
Does revoking a TikTok token stop its webhooks?
Yes. TikTok sends the app no more comment.update events for that account until the owner authorizes the app again.
Where does the TikTok business_id come from?
From open_id in the token response, which Accounts API calls take as business_id. /tt_user/token_info/get/ returns the same ID as creator_id.
Keep reading
Connect your first channel in two minutes.
No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.
- 3 days free
- Cancel any time
- Official APIs only
- Monitored 24/7
Verified on