About the Authentication API

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:

  • Register new members and manage their authentication tokens.
  • Log in existing members and maintain their session tokens for secure access.

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.

Use cases

Terminology

  • Captcha token: A token used to verify that the registration or login request is made by a human and not a bot.
  • Identity: The unique identifier and profile information of a member.
  • Factor: An authentication factor used in multi-factor authentication processes.
Did this help?

Member Registration and Login: Sample Use Cases and Flows

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.

Log in an existing member and generate a session token for subsequent authenticated API calls

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:

  1. Call Login V 2 to log in the existing member.
  2. Using the session token sent in the response, generate and use the member token for subsequent authenticated API calls.
Did this help?

Retrieve Tokens

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 TypeDescriptionRequired Fields
authorization_codeUsed to obtain access and refresh tokens for an authenticated visitor after obtaining an authorization code.redirectUri
code
codeVerifier
refresh_tokenUsed to obtain an access token using a refresh token after the previous one expires.refreshToken
anonymousUsed to obtain access and refresh tokens for an unauthenticated site visitor.N/A

Syntax

Copy
POST https://www.wixapis.com/oauth2/token

Body Params

NameTypeDescription
clientIdstringRequired: ID of the Wix OAuth app requesting authorization.
grantTypestringType of request flow.
Supported values:
- authorization_code
- refresh_token
- urn:ietf:params:oauth:grant-type:device_code
- anonymous
refreshTokenstringRefresh token. Required when using the refresh_token grant type.
redirectUristringRedirect 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.
codestringAuthorization code. Retrieved using the redirect API. Required when using the authorization_code grant type.
codeVerifierstringCode 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.

Response Object

Success Response

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:

NameTypeDescription
access_tokenstringAccess token.
expires_inintegerNumber of seconds until the token expires.
token_typestringToken type. Only Bearer is supported.
refresh_tokenstringRefresh token.

Error Responses

There are two types of error responses:

Invalid redirect URI

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 MessageDescription
invalid_requestThe request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_clientThe client is not authorized to request an access token using this method.
access_deniedThe request was denied.
server_errorThe 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_unavailableThe 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.)

Other invalid requests

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 MessageDescription
invalid_requestThe request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
invalid_clientClient authentication failed.
invalid_grantThe 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_clientThe authenticated client is not authorized to use this authorization grant type.
unsupported_grant_typeThe authorization grant type is not supported by the authorization server.

Examples

Retrieve a visitor access token

All examples use the application/json content type.

Request:

Copy
curl --location 'https://www.wixapis.com/oauth2/token' \ --header 'Content-Type: application/json' \ --data '{ "clientId": "e345f72c-a4ef-46b6-8b0f-f6b2cd66b78b", "grantType": "anonymous" }'

Response

Copy
{ "access_token": "OauthNG.JWS.eyJraWQiOiJZSEDI5M...", "token_type": "Bearer", "expires_in": 14400, "refresh_token": "AQS.eyJraWQiOiJZSEJzdUpwSCIsImFs..." }

Refresh an access token

Request:

Copy
curl --location 'https://www.wixapis.com/oauth2/token' \ --header 'Content-Type: application/json' \ --data '{ "refresh_token": "AQS.eyJraWQiOiJZSEJzdUpwSCIsImFs...", "grantType": "refresh_token" }'

Response

Copy
{ "access_token": "OauthNG.JWS.eyJraWQiOiJZSEDI5M...", "token_type": "Bearer", "expires_in": 14400, "refresh_token": "AQS.eyJraWQiOiJZSEJzdUpwSCIsImFs..." }

Retrieve an access token for an authenticated visitor

Request:

Copy
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

Copy
{ "access_token": "OauthNG.JWS.eyJraWQiOiJZSEDI5M...", "token_type": "Bearer", "expires_in": 14400, "refresh_token": "AQS.eyJraWQiOiJZSEJzdUpwSCIsImFs..." }
Did this help?

POST

Register V 2


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.

Endpoint
POST
https://www.wixapis.com/_api/iam/authentication/v2/register

Body Params
loginIdLoginIdRequired

Identifier of the registering member.


passwordstring

Password of the registering member.


profileProfile

Profile information of registering member.


captchaTokensArray <CaptchaToken>

CAPTCHA tokens, when CAPTCHA setting is on.


clientMetaDatastruct

Additional data that's relevant for the flow.

Response Object
statestring

Current state of the login or registration process.


sessionTokenstring

Session token. If state is not SUCCESS, this field is undefined.


stateTokenstring

Token that represents the current state of the login or registration process.


identityIdentity

Identity of the current member.


additionalDataMap <string, CustomValue>format map

Additional data relevant to the login or registration process.

Request
cURL
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..." }] }'
Response
JSON
{ "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": [] } } }
Errors
400Invalid Argument

There are 13 errors with this status code:

403Permission Denied

There are 5 errors with this status code:

409Already Exists

There is 1 error with this status code:

429Resource Exhausted

There is 1 error with this status code:

500Internal

There are 2 errors with this status code:

See the entire list and learn more about Wix errors.

Did this help?

POST

Login V 2


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.

Endpoint
POST
https://www.wixapis.com/_api/iam/authentication/v2/login

Body Params
loginIdLoginIdRequired

Identifier of identity logging in.


passwordstring

Password of the identity logging in.


captchaTokensArray <CaptchaToken>

CAPTCHA tokens, when CAPTCHA setting is on.


clientMetaDatastruct

Additional data that's relevant for the flow.

Response Object
statestring

Current state of the login or registration process.


sessionTokenstring

Session token. If state is not SUCCESS, this field is undefined.


stateTokenstring

Token that represents the current state of the login or registration process.


identityIdentity

Identity of the current member.


additionalDataMap <string, CustomValue>format map

Additional data relevant to the login or registration process.

Request
cURL
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..." }] }'
Response
JSON
{ "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": [] } } }
Errors
400Invalid Argument

There are 2 errors with this status code:

401Unauthenticated

There is 1 error with this status code:

403Permission Denied

There are 2 errors with this status code:

429Resource Exhausted

There is 1 error with this status code:

500Internal

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Did this help?