Login

This section walks you through testing the Violet APIs. Make sure you have already signed up at channel.violet.io/signup and created an application in the previous step. If you haven't, please go through Create a Violet Application.

You will need your App ID and App Secret in order to complete this step.

Login

This API tests your connection to Violet by logging into your Application. Add X-Violet-App-Id and X-Violet-App-Secret added to your headers for login. These are available from the application you created on channel.violet.io. Every request after login will require these header params for authentication, along with the X-Violet-Token that you get from login and refreshing your token.

While your username and password will be the same across environments (test and live) as will your X-Violet-App-Id, this is not true for your X-Violet-App-Secret.

The X-Violet-App-Secret you retrieve from the Channel dashboard is different depending on the live/test mode toggle. You must use the correct app secret that corresponds to the environment you are trying to login to: test for sandbox-api.violet.io and live for api.violet.io.

In addition to the headers mentioned above, include your username (your username is the email you signed up with) and password. If successful, an access token will be returned in the response body for use in additional requests against the API along with information about your API.

While the User Management feature of the Dashboard allows multiple users to login and view the dashboard, only an App's "Owner" username and password will allow you to generate a token. You can view who your App's owner is on the team view

Login

post

Header parameters

X-Violet-App-SecretstringRequired

Please note that App Secrets are different depending on environment (test/live) please make sure you have retrieved the correct app secret from the Dashboard.

X-Violet-App-Idinteger · int32Required

Body

Login Request

usernamestringRequired

Username

passwordstringRequired

Password

Responses

default

default response

application/json

Login Response

idinteger · int64Read-onlyOptional

first_namestringRequired

The users first name

last_namestringRequired

The users last name

passwordstringRequired

The users raw desired password

emailstringRequired

The users unique email address

typestring · enumRequired

The allowed values for the user type

Possible values:

verifiedbooleanOptional

If a user has verified their emailed address

statusstring · enumOptional

The status of the user. Note the lower case possible values as opposed to other status enums, this is a legacy issue that is maintained for backwards compatibility.

Possible values:

date_createdstring · date-timeOptional

Date of creation

date_last_modifiedstring · date-timeOptional

Date of last update

tos_acceptedbooleanOptional

Terms of Service Accepted

payment_configuredbooleanOptional

Is the Users Payment Settings Configured

privacy_policy_acceptedbooleanOptional

Privacy Policy Accepted

country_codestring · enumOptional

Country Code

Possible values:

tokenstringOptional

Token

refresh_tokenstringOptional

Refresh Token

merchant_idinteger · int32Optional

Merchant ID. Should only be used during merchant validation. Expect property to be null.

merchant_idsinteger · int32[]Optional

Merchant IDs

store_urlstringOptional

Store Url

post/login

POST /v1/login HTTP/1.1
Host: sandbox-api.violet.io
X-Violet-App-Secret: text
X-Violet-App-Id: 1
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "username": "text",
  "password": "text"
}

default

default response

{
  "id": 1,
  "first_name": "text",
  "last_name": "text",
  "password": "text",
  "email": "text",
  "type": "SUPER_ADMIN",
  "verified": true,
  "status": "inactive",
  "date_created": "2026-01-01T00:00:00.000Z",
  "date_last_modified": "2026-01-01T00:00:00.000Z",
  "roles": [
    {
      "name": "text",
      "permissions": [
        {
          "name": "text",
          "description": "text"
        }
      ]
    }
  ],
  "tos_accepted": true,
  "payment_configured": true,
  "privacy_policy_accepted": true,
  "country_code": "US",
  "token": "text",
  "refresh_token": "text",
  "merchant_id": 1,
  "merchant_ids": [
    1
  ],
  "store_url": "text"
}

Refresh your Token

Use the Refresh Token to get a new token. This is an operation you will have to do on a regular basis. You can use your App Id and App Secret with a refresh token to get a new token. This saves the step of having to send your username and password each time to get a new token.