The Wix Authentication API enables you to implement custom member registration and login for headless projects. Use this API to manage user authentication, while ensuring secure access.
With the Wix Authentication API, you can:
The Register V 2 and Login V 2 methods include a sessionToken
in their response. You can use the session token to get the site member's access and refresh tokens.
Note: You can use the Redirects API to let Wix handle authentication.
This article shares some possible use cases your app could support, as well as a sample flow that could support each use case. This can be a helpful jumping-off point as you plan your Headless project's implementation.
This flow guides you through logging in an existing member and generating a session token for authenticated API calls using the Wix Authentication API.
To log in an existing member and generate a session token:
Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves access and refresh tokens that a Wix OAuth app can use to make API calls on behalf of a site visitor.
This endpoint accepts requests with both application/json
and application/x-www-form-urlencoded
content types. The parameter names are the same for both content types.
The endpoint supports several grantType
flows for obtaining tokens. Each flow has its own set of required fields.
Here are the supported flows with their required fields:
Grant Type | Description | Required Fields |
---|---|---|
authorization_code | Used to obtain access and refresh tokens for an authenticated visitor after obtaining an authorization code. | redirectUri code codeVerifier |
refresh_token | Used to obtain an access token using a refresh token after the previous one expires. | refreshToken |
anonymous | Used to obtain access and refresh tokens for an unauthenticated site visitor. | N/A |
POST https://www.wixapis.com/oauth2/token
Name | Type | Description |
---|---|---|
clientId | string | Required: ID of the Wix OAuth app requesting authorization. |
grantType | string | Type of request flow. Supported values: - authorization_code - refresh_token - urn:ietf:params:oauth:grant-type:device_code - anonymous |
refreshToken | string | Refresh token. Required when using the refresh_token grant type. |
redirectUri | string | Redirect URI that passed to the redirect API when requesting an authorization code. Used to verify that the authentication and token requests are from the same source. Required when using the authorization_code grant type. |
code | string | Authorization code. Retrieved using the redirect API. Required when using the authorization_code grant type. |
codeVerifier | string | Code for PKCE verification. This is the encrypted version of the codeChallenge that was sent using the redirect API. Required when using the authorization_code grant type. |
If a request succeeds, the server returns an HTTP 200
status code with an application/json
content type. The response body is a JSON object with the following fields:
Name | Type | Description |
---|---|---|
access_token | string | Access token. |
expires_in | integer | Number of seconds until the token expires. |
token_type | string | Token type. Only Bearer is supported. |
refresh_token | string | Refresh token. |
There are two types of error responses:
If the request includes an invalid redirectUri
parameter, the server returns an HTTP 302
status code and redirects the request back to the client. The redirect URL contains a fragment with an error
key and one of the following values:
Error Message | Description |
---|---|
invalid_request | The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. |
unauthorized_client | The client is not authorized to request an access token using this method. |
access_denied | The request was denied. |
server_error | The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.) |
temporarily_unavailable | The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.) |
If the request is invalid for any other reason, the server returns an HTTP 400
status code with an application/json
content type. The response body is a JSON object with an error
key and one of the following values:
Error Message | Description |
---|---|
invalid_request | The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. |
invalid_client | Client authentication failed. |
invalid_grant | The provided authorization code or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. |
unauthorized_client | The authenticated client is not authorized to use this authorization grant type. |
unsupported_grant_type | The authorization grant type is not supported by the authorization server. |
All examples use the application/json
content type.
Request:
curl --location 'https://www.wixapis.com/oauth2/token' \
--header 'Content-Type: application/json' \
--data '{
"clientId": "e345f72c-a4ef-46b6-8b0f-f6b2cd66b78b",
"grantType": "anonymous"
}'
Response
{
"access_token": "OauthNG.JWS.eyJraWQiOiJZSEDI5M...",
"token_type": "Bearer",
"expires_in": 14400,
"refresh_token": "AQS.eyJraWQiOiJZSEJzdUpwSCIsImFs..."
}
Request:
curl --location 'https://www.wixapis.com/oauth2/token' \
--header 'Content-Type: application/json' \
--data '{
"refresh_token": "AQS.eyJraWQiOiJZSEJzdUpwSCIsImFs...",
"grantType": "refresh_token"
}'
Response
{
"access_token": "OauthNG.JWS.eyJraWQiOiJZSEDI5M...",
"token_type": "Bearer",
"expires_in": 14400,
"refresh_token": "AQS.eyJraWQiOiJZSEJzdUpwSCIsImFs..."
}
Request:
curl --location 'https://www.wixapis.com/oauth2/token' \
--header 'Content-Type: application/json' \
--data '{
"clientId": "e345f72c-a4ef-46b6-8b0f-f6b2cd66b78b",
"grantType": "authorization_code",
"redirectUri": "https://wix-events-nextjs.vercel.app/callback",
"code": "OLI66BELkX"
}'
Response
{
"access_token": "OauthNG.JWS.eyJraWQiOiJZSEDI5M...",
"token_type": "Bearer",
"expires_in": 14400,
"refresh_token": "AQS.eyJraWQiOiJZSEJzdUpwSCIsImFs..."
}
Registers a new member.
Typically, after a successful registration, you generate and use member tokens for the
registered member so that subsequent API calls are called as part of a member session.
Use the sessionToken
in the response to get the site member's access and refresh tokens.
If the email used to register the member already exists as a contact email, the registering member need to verify the email address using a code that is sent to the address.
Identifier of the registering member.
Password of the registering member.
Profile information of registering member.
CAPTCHA tokens, when CAPTCHA setting is on.
Additional data that's relevant for the flow.
Current state of the login or registration process.
Session token. If state
is not SUCCESS
, this field is undefined.
Token that represents the current state of the login or registration process.
Identity of the current member.
Additional data relevant to the login or registration process.
curl -X POST \
'https://www.wixapis.com/_api/iam/authentication/v2/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"login_id": {
"email": "test@test.com"
},
"password": "my-weak-password",
"profile": {
"nickname": "test",
"emails": ["test@test.com"],
"phones": ["+1-72149124712"],
"customFields": []
},
"captcha_tokens": [{
"Recaptcha": "03AAYGu2Q0STS4gydphoHzHuDW7EFHDzohvovlwgE-bpDbB1..."
}]
}'
{
"state": "SUCCESS",
"session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"identity": {
"id": "16a5995f-4514-491b-b054-ffee5adf5af2",
"revision": "1",
"createdDate": "2022-09-15T14:28:36Z",
"updatedDate": "2022-09-15T14:28:37Z",
"identityProfile": {
"nickname": "test",
"emails": ["test@test.com"],
"phones": ["+1-72149124712"],
"privacyStatus": "PUBLIC",
"customFields": []
},
"email": {
"address": "test@test.com",
"isVerified": false
},
"status": {
"name": "ACTIVE",
"reasons": []
}
}
}
There are 13 errors with this status code:
There are 5 errors with this status code:
There is 1 error with this status code:
There is 1 error with this status code:
There are 2 errors with this status code:
See the entire list and learn more about Wix errors.
Logs in an existing member.
Typically, after a successful login, you generate and use member tokens for the
logged-in member so that subsequent API calls are called as part of a member session.
Use the sessionToken
in the response to get the site member's access and refresh tokens.
Identifier of identity logging in.
Password of the identity logging in.
CAPTCHA tokens, when CAPTCHA setting is on.
Additional data that's relevant for the flow.
Current state of the login or registration process.
Session token. If state
is not SUCCESS
, this field is undefined.
Token that represents the current state of the login or registration process.
Identity of the current member.
Additional data relevant to the login or registration process.
curl -X POST \
'https://www.wixapis.com/_api/iam/authentication/v2/login' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"login_id": {
"email": "test@test.com"
},
"password": "my-password",
"captcha_tokens": [{
"Recaptcha": "03AAYGu2Q0STS4gydphoHhvovlwgE-bpDbB1..."
}]
}'
{
"state": "SUCCESS",
"session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"identity": {
"id": "16a5995f-4514-491b-b054-ffee5adf5af2",
"revision": "1",
"createdDate": "2022-09-15T14:28:36Z",
"updatedDate": "2022-09-15T14:28:37Z",
"identityProfile": {
"nickname": "test",
"emails": ["test@test.com"],
"phones": ["+1-72149124712"],
"privacyStatus": "PUBLIC",
"customFields": []
},
"email": {
"address": "test@test.com",
"isVerified": false
},
"status": {
"name": "ACTIVE",
"reasons": []
}
}
}
There are 2 errors with this status code:
There is 1 error with this status code:
There are 2 errors with this status code:
There is 1 error with this status code:
There is 1 error with this status code:
See the entire list and learn more about Wix errors.