Handle Visitors

Share your feedback
Reach out to us with feedback and suggestions to improve the Wix Headless experience, and join the Headless channel of the Devs on Wix Discord community to discuss features and connect with our growing community of developers.

In order to handle site visitor sessions you need to generate, manage, and use visitor tokens. Use these tokens when making requests to Wix APIs on behalf of a visitor to maintain the visitor's session.

Prerequisites

Generate new visitor tokens

Generate new visitor tokens using the Token endpoint.

When calling the Token endpoint, send the following parameters:

  • clientId: The client ID of the OAuth app your project is using.
  • grantType: Set as "anonymous" to get visitor tokens.
Copy
1
curl --location 'https://www.wixapis.com/oauth2/token' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
"clientId": "<CLIENT_ID>",
5
"grantType": "anonymous"
6
}'

Note: You can also get tokens using URL-encoded data instead of JSON data.

Copy
1
curl --location 'https://www.wixapis.com/oauth2/token' \
2
--header 'Content-Type: application/x-www-form-urlencoded' \
3
--data-urlencode 'client_id=<CLIENT_ID>' \
4
--data-urlencode 'grant_type=anonymous'

The Token endpoint responds with:

  • access_token: An access token used to authorize API calls.
  • expires_in: The number of seconds before the access token expires. Access tokens expire after 4 hours (14,400 seconds).
  • refresh_token: A refresh token used to get a new access token.
Copy
1
{
2
"access_token": "OauthNG.JWS.eyJraWQiOiJZSEJzdUpwSCIsImFsZyI6IkhTMjU2In0...",
3
"token_type": "Bearer",
4
"expires_in": 14400,
5
"refresh_token": "JWS.eyJraWQiOiJZSEJzdUpwSCIsImFsZyI6IkhTMjU2In0..."
6
}

Once you have tokens, you can use them to make authenticated calls to APIs on behalf of the current visitor.

Store tokens for later

If you want to be able to restore the current session at some point later, store your visitor tokens locally, for example in localStorage, a cookie, or a local file.

For example, after generating a visitor token, you can store it in a cookie with a max age of 4 hours. Then, before making API calls, try reading the token from the cookie.

  • If the cookie still exists, you can use the access token you stored in the cookie to make the API call.
  • If the cookie no longer exists, you can use your refresh token to renew your visitor tokens, and then make the API call with the new access token.

Renew visitor tokens

To renew visitor tokens, call the Token endpoint again, this time with the following parameters:

  • refresh_token: The refresh token returned from the previous call to the Token endpoint.
  • grantType: Set as "refresh_token" to get renewed visitor tokens based off your current refresh token.
Copy
1
curl --location 'https://www.wixapis.com/oauth2/token' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
"refresh_token": "<REFRESH_TOKEN>",
5
"grantType": "refresh_token"
6
}'

The Token endpoint responds with:

  • access_token: An access token used to authorize API calls.
  • expires_in: The number of seconds before the access token expires. Access tokens expire after 4 hours (14,400 seconds).
  • refresh_token: A refresh token used to get a new access token.
Copy
1
{
2
"access_token": "OauthNG.JWS.eyJraWQiOiJZSEJzdUpwSCIsImFsZyI6IkhTMjU2In0...",
3
"token_type": "Bearer",
4
"expires_in": 14400,
5
"refresh_token": "JWS.eyJraWQiOiJZSEJzdUpwSCIsImFsZyI6IkhTMjU2In0..."
6
}
Was this helpful?
Yes
No